Job Management API

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

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

This document describes two types of jobs that you can define: CatalogAutoRefresh, which you can use to update catalogs, and ReferencedResourceVersionUpdate, which you can use to update slot types and interaction models.

An execution is a different type of resource that models the time and status of the job. For example, an execution of a CatalogAutoRefresh job has a time stamp that specifies when the execution of the job starts, and a status to describe the state of the execution. Executions are scheduled automatically when you create a job and also when a previous execution is finished. You can read the details of all executions of a job. You can also cancel the next execution of a job.

The endpoint for SMAPI operations is https://api.amazonalexa.com. Each request must have an Authorization header with its value set to the access token retrieved from Login with Amazon.

Create a Job Definition
Read Job Definition
List Jobs for Vendor ID
Delete Job
List Execution History
Cancel Next Execution
Enable or Disable Job

Create a Job Definition

You can create two types of job definitions: CatalogAutoRefresh and ReferencedResourceVersionUpdate. For example, you can use this API with the type set to CatalogAutoRefresh to specify a catalog ID and how often you want the catalog to get updated. In your skill you can specify the referenced entity that you want to get triggered for an update whenever the catalog is refreshed. Skills can use this API with the type set to ReferencedResourceVersionUpdate to link a catalog ID with a skill ID.

For skills with shared slots, invoke this API twice with the type set to ReferencedResourceVersionUpdate in both invocations. In the first invocation, link a catalog ID with a slot ID. Then, link the slot ID with a skill ID.

Request

POST /v1/skills/api/custom/interactionModel/jobs

Body for CatalogAutoRefresh

{
   "vendorId": "String",
   "jobDefinition": {
      "type": "CatalogAutoRefresh",
      "resource": {
          "id": "String",
          "type": "Catalog"
      },
      "trigger": {
          "type": "Scheduled",
          "hour": Integer,
          "dayOfWeek": Integer
      },
      "status": "Enum"
   }           
}

Request Body Parameters for CatalogAutoRefresh

Field	Description	Parameter Type	Required?
`vendorId`	To get your vendor ID, go to https://developer.amazon.com/mycid.html.	String	Yes
`jobDefinition.type`	"CatalogAutoRefresh"	String	Yes
`resource.id`	The ID of the resource.	String	Yes
`resource.type`	"Catalog", "SlotType", or "InteractionModel"	String	Yes
`trigger.type`	"Scheduled"	String	Yes
`trigger.hour`	Starting hour of the day for the execution to run. Set it to 0, 4, 8, 12, 16, or 20.	Integer	Yes
`trigger.dayOfWeek`	The day of week. Specify this value to indicate that you want the job to be scheduled weekly. If you don't specify a value here, the job runs daily by default.	Integer	Required for weekly schedule.
`status`	Set to "ENABLED" or let it be null.	Enum	No

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

Body for ReferencedResourceVersionUpdate

{
    "vendorId": "String",
    "jobDefinition": {
        "type": "ReferenceVersionUpdate",
        "resource": {
            "type": Enum,
            "id": "String",
            "locales": ["String"]
        },
        "references": [
           {
             "type": Enum,
             "id": "String"
           }
        ],
        "trigger": {
            "type": "ReferencedResourceJobsComplete"
        },
        "publishToLive": Boolean,
        "status": "Enum"         
    }
}

Request Body Parameters for ReferencedResourceVersionUpdate

Field	Description	Parameter Type	Required?
`vendorId`	To get your vendor ID, go to https://developer.amazon.com/mycid.html.	String	Yes
`resource.id`	The ID of resource.	string	Yes
`resource.type`	"Catalog", "SlotType", or "InteractionModel"	String	Yes
`resource.locales`	The default is all available locales for the given skill.	String	No
`references`	Referenced resources that the "resource" field is dependent on.	resource array	No
`publishToLive`	Whether to publish the updated InteractionModel.	Boolean	Yes
`status`	Set to "ENABLED" or let it be null.	Enum	No

Response

HTTP/1.1 200 OK

/v1/skills/api/custom/interactionModel/jobs/{jobId}

The jobId in the response has the following format: "amzn1.ask.jobId.$(UUID)". UUID is 16 octets (128 bits). Example: amzn1.ask.jobId.e0de19c7-43a8-4738-afa7-3a7f1b3c0367

Exceptions

HTTP/1.1 400 Validation Error

{
  "errors":  [
     {
        "code": "String",
        "message":  "String"
     }
  ]
}

Code	Message
INVALID_JOB_DEFINITION	The job definition isn't valid.
INVALID_JOB_TYPE	The job type can't be changed after creation.
INVALID_CATALOG_TYPE	The catalog type is incompatible with the job definition. For example, the catalog doesn't contain a URL that can be automatically pulled from.
DUPLICATE_JOB_DEFINITION	There is already the same type of job associated with the specified entityId.
EXCEEDED_JOB_NUMBER_LIMIT	You've exceeded the limit, which is 20 jobs.
INVALID_DEPENDENCY	The reference list contains a resource that isn't referenced by the job's main resource.
TIME_WINDOW_UNAVAILABLE	The specified time window is full. Specify a different time window.

HTTP/1.1 401 Unauthorized
The authorization token is invalid, expired, or doesn't have access to the resource.

HTTP/1.1 403 Forbidden
You don't have permission to perform actions on this resource.

HTTP/1.1 404 Not Found

HTTP/1.1 429 Too Many Requests
Request limit exceeded. Throttling criteria include total requests per API, ClientId, and CustomerId.

HTTP/1.1 500 Internal Server Error

HTTP/1.1 503 Service Unavailable

Read Job Definition

Request

GET /v1/skills/api/custom/interactionModel/jobs/{jobId}

The jobId in the request path is the identifier of the job definition. It is required.

Response

Response for CatalogAutoRefresh

{
    "type": "CatalogAutoRefresh",
    "resource": {
        "id": "String",
        "type": Enum
    },
    "trigger": {
        "type": "Scheduled",
        "hour": Integer,
        "dayOfWeek": Integer
    },
    "status": Enum             
}

Response for ReferenceVersionUpdate

{
    "type": "ReferenceVersionUpdate",
    "resource": {
        "type": Enum,
        "id": "String"
    },
    "references": [
       {
        "type": Enum,
        "id": "String"
       }
    ],
    "trigger": {
        "type": "ReferencedResourceJobsComplete"
    },
    "publishToLive": Boolean,
    "status": Enum         
}

Exceptions

HTTP/1.1 401 Unauthorized
The authorization token is invalid, expired, or doesn't have access to the resource.

HTTP/1.1 403 Forbidden
You don't have permission to perform actions on this resource.

HTTP/1.1 404 Not Found

HTTP/1.1 429 Too Many Requests
Request limit exceeded. Throttling criteria include total requests per API, ClientId, and CustomerId.

HTTP/1.1 500 Internal Server Error

HTTP/1.1 503 Service Unavailable

List Jobs for Vendor ID

Request

GET /v1/skills/api/custom/interactionModel/jobs?vendorId=vendorId&maxCount=maxCount&nextToken=nextToken

Path Parameters

Parameter	Description	Required
maxCount	The maximum number of jobs to return per page. The default is 50.	No
nextToken	The token to use to get the next page.	No

Response

Response Body

{
   "jobs": [{
       "jobId": "String",
       "jobType": Enum,  
       "status": Enum
     }
  ],
  "paginationContext": {
       "nextToken": "String"
  },
  "_links": {
        "next": {
           "href": "String"
        },
        "self": {
           "href": "String"
        }
  }
}

The status can be SUCCESS, FAILURE, IN_PROGRESS, SCHEDULED, or CANCELED.

Exceptions

HTTP/1.1 401 Unauthorized
The authorization token is invalid, expired, or doesn't have access to the resource.

HTTP/1.1 403 Forbidden
You don't have permission to perform actions on this resource.

HTTP/1.1 404 Not Found

HTTP/1.1 429 Too Many Requests
Request limit exceeded. Throttling criteria include total requests per API, ClientId, and CustomerId.

HTTP/1.1 500 Internal Server Error

HTTP/1.1 503 Service Unavailable

Delete Job

Request

DELETE /v1/skills/api/custom/interactionModel/jobs/{jobId}

Response

HTTP/1.1 204 Success
The response to this operation doesn't have any content.

Exceptions

Code	Message
JOB_IN_USE	Other jobs depend on this job. Update or delete the dependent, then try again.
ON_GOING_EXECUTION	The job is currently running. Try again later.

HTTP/1.1 401 Unauthorized
The authorization token is invalid, expired, or doesn't have access to the resource.

HTTP/1.1 403 Forbidden
You don't have permission to perform actions on this resource.

HTTP/1.1 404 Not Found

HTTP/1.1 429 Too Many Requests
Request limit exceeded. Throttling criteria include total requests per API, ClientId, and CustomerId.

HTTP/1.1 500 Internal Server Error

HTTP/1.1 503 Service Unavailable

List Execution History

This operation lists the execution history of the specified job.

Request

GET /v1/skills/api/custom/interactionModel/jobs/{jobId}/executions?maxCount=maxCount&sortDirection=asc&nextToken=nextToken

Path Parameters

Parameter	Description	Required
jobId	The ID of the job definition.	Yes
maxCount	The maximum number of results to return per page. The default is 50.	No
nextToken	The token to use to get the next page.	No
sortDirection	How you want the results to be sorted. The sorting is based on the executionTimestamp field. Specify "asc" for ascending or "desc" for descending.	No

Response

HTTP/1.1 20O OK

Response Body

{
   "executions": [{
       "executionId": "String",
       "executionTimestamp": "String",    //ISO-8601
       "errorCode": "String", 
       "status": Enum,     
       "errorDetails": {
          "executionMetadata": [{
              "jobId": "String",
              "errorCode": "String",
              "status": Enum
          },
          {
              "jobId": "String",
              "errorCode": "String",
              "status": Enum
          }]
       }       
     }
  ],
  "paginationContext": {
       "nextToken": "String"
  },
  "_links": {
        "next": {
           "href": "String"
        },
        "self": {
           "href": "String"
        }
  }
}

Response Body Parameters

Parameter	Description
executionTimestamp	The expected time to start the execution. It can be in the past.
status	The current status of the update job. The following are the possible values: SUCCESS, FAILURE, IN_PROGRESS, SCHEDULED.
errorCode	If the status is FAILURE, this error code explains what went wrong.
executionMetadata	Details of the sub-executions.
jobId	The ID of the execution job.

Exceptions

HTTP/1.1 400

Code	Message	State of resources
ON_GOING_BUILD	Execution failed because the entity was being built and the retry period was exceeded.	Dev models not updated.
INTERNAL_ERROR	The job failed due to a system error.	Live skill models not updated. Look for the latest version descriptions in development stages to see if development models were updated.
INVALID_REQUEST	Update request was rejected because of a 400 error "_error_code_from_service".	Development model not updated.

HTTP/1.1 401 Unauthorized
The authorization token is invalid, expired, or doesn't have access to the resource.

HTTP/1.1 403 Forbidden
You don't have permission to perform actions on this resource.

HTTP/1.1 404 Not Found

HTTP/1.1 429 Too Many Requests
Request limit exceeded. Throttling criteria include total requests per API, ClientId, and CustomerId.

HTTP/1.1 500 Internal Server Error

HTTP/1.1 503 Service Unavailable

Cancel Next Execution

Cancel the next execution of the specified job.

Request

DELETE /v1/skills/api/custom/interactionModel/jobs/{jobId}/executions/{executionId}

Path Parameters

Parameter	Description
jobId	The ID of the job definition.
executionId	This needs to be the ID of the latest execution, otherwise you get an exception.

Response

HTTP/1.1 204 Accepted

Exceptions

HTTP/1.1 400

{
  "errors":  [
     {
        "code": "String",
        "message":  "String"
     }
  ]
}

Code	Description
INVALID_JOB_TYPE	You can only cancel jobs of type `CatalogAutoRefresh`.
INVALID_EXECUTION	This execution can't be canceled because the job is disabled or the execution has already been canceled or deleted.

HTTP/1.1 401 Unauthorized
The authorization token is invalid, expired, or doesn't have access to the resource.

HTTP/1.1 403 Forbidden
You don't have permission to perform actions on this resource.

HTTP/1.1 404 Not Found

HTTP/1.1 429 Too Many Requests
Request limit exceeded. Throttling criteria include total requests per API, ClientId, and CustomerId.

HTTP/1.1 500 Internal Server Error

HTTP/1.1 503 Service Unavailable

Enable or Disable Job

Request

PUT /v1/skills/api/custom/interactionModel/jobs/{jobId}/status

Request Body

{
    "status": Enum
}

Path Parameters

Parameter	Description	Required
jobId	The ID of the job definition.	Yes
status	ENABLED or DISABLED	Yes

Response

HTTP/1.1 204 Accepted

Exceptions

HTTP/1.1 400

{
  "errors":  [
     {
        "code": "String",
        "message":  "String"
     }
  ]
}

Code	Description
INVALID_JOB_STATUS	The job status is not defined. Specify only ENABLED or DISABLED.
INVALID_EXECUTION	This execution can't be canceled because the job is disabled or the execution has already been canceled or deleted.

HTTP/1.1 401 Unauthorized
The authorization token is invalid, expired, or doesn't have access to the resource.

HTTP/1.1 403 Forbidden
You don't have permission to perform actions on this resource.

HTTP/1.1 404 Not Found

HTTP/1.1 429 Too Many Requests
Request limit exceeded. Throttling criteria include total requests per API, ClientId, and CustomerId.

HTTP/1.1 500 Internal Server Error

HTTP/1.1 503 Service Unavailable

Last updated: Jan 03, 2023