Beta Signup

Are you interested in trying out the API right away?

Are you willing to give us feedback on your experience?

If so, sign up for Beta access!



Job Scheduler API


The Job Scheduler API allows you to create and manage jobs that will run one or more times in the future.


Overview

The Job Scheduler works by accepting requests for future notifications. Each job has a specific date or schedule and a user-specified callback URL to contact when the job fires. This callback URL is an entry point which tells your application that its times to process the job.

In addition, each job may include a payload which will be provided when notifying your application. In this way your application may provide contextual data needed to process the job in the future.

This is a RESTful API which is accessed over HTTP. Any language which can make HTTP requests can use the API to interact with the scheduler service. It accepts requests in XML or JSON, and can generate responses in XML or JSON (and in some cases plain text).

What's in a job?

A job structure has several fields that describe the job and it's payload. These fields and examples of both request and response documents in each of the supported formats are listed below:

id A UUID which uniquely identifies a job in the job scheduling system. These are automatically assigned when creating a job and cannot be changed.
account The user account which the job belongs to, automatically assigned when creating a job. The account of a created job cannot be changed.
url Callback URL of the user application, provided when creating a job. This is the URL the job scheduler will post to when the job fires. If a data document was provided for the job, it will be sent as the request body.
signature (optional) Signature optionally provided by the user application so that it can verify the authenticity of the callback payload.
contentType (optional) Optional field describing the content-type of the user provided callback payload. If there is a payload specified, the content-type of callback request will be set to this value, if it is provided, or application/octet-stream if this field is missing.
data (optional) Optional payload to include when calling-back the user application. This field may be any content that can be properly encoded for transport over HTTP, such as an XML or JSON document, plain text, or binary attachment. For sensitive data, user applications are encouraged to encrypt the payload, provided that it is appropriately encoded. The size of the data field is currently limited to 2048 bytes.
when A single ISO8601 date in the future when this job will fire. If the when field is provided, the job will run exactly once at the specified time and then be purged from the system. This time may be provided in any timezone. The when field or the cron must be specified, but not both.
cron A cron expression describing the firing schedule for the job. The job may not be specified to fire more often than once every ten minutes. So long as a future firing time exists in the schedule, the job will remain active. If, after firing, the schedule will no longer cause the job to be fired, it will be purged from the system. The cron or the when field must be specified, but not both.
next An ISO8601 date indicating the next firing time for job. This field is automatically generated for jobs which have the cron field set, and may not be changed. It will not be returned for a job that uses the when field since that field already describes the next and only firing time for the job. Note that this time is always reported in UTC.

Request Headers

These headers may be sent by your application to control the processing of the API call.

Accept The Accept header tells the API which response data format(s) your application can process. Valid values are text/xml or application/xml for an XML formatted response body or application/json for a JSON formatted response body.
Content-Type The Content-Type header tells the API which request data format(s) your application is providing. Valid values for most API calls are text/xml or application/xml for an XML formatted request body or application/json for a JSON formatted request body.

Response Headers

These headers will be included when responding to an API call.

Content-Type The Content-Type header indicates the API is formatting the response. The API will choose the response format based on the Accept header provided in the request, according to quality factor rules.
Content-Length The Content-Length header provides the size in bytes of the response document.


Jobs API

List

https://job-sheduling.info/1/jobs

Provides a list of all job ids for the account. See an example text, JSON or XML response.

Version1
MethodGET
Request FormatsNone
Response Formats text/plain
application/json
text/xml
application/xml

Get

https://job-sheduling.info/1/jobs/<id>

Retrieve the details of the specified job. See an example XML or JSON request and JSON or XML response.

Version1
MethodGET
Parametersid - the id of the job to retrieve
Request FormatsNone
Response Formats application/json
text/xml
application/xml

Create One-time or Recurring Job

https://job-sheduling.info/1/jobs

Creates a new one-time or recurring job from the job detail document posted as the message body. This call returns either the job id for the full job details. See an example XML or JSON request and text, JSON or XML response.

Version1
MethodPOST
Request Formats application/json
text/xml
application/xml
Response Formats text/plain
application/json
text/xml
application/xml

Update Job

https://job-sheduling.info/1/jobs/<id>

Updates an existing one-time or recurring job from the job detail document posted as the message body. This call returns either the job id for the full job details. See an example XML or JSON request and text, JSON or XML response.

Version1
MethodPUT
Parametersid - the id of the job to update
Request Formats application/json
text/xml
application/xml
Response Formats text/plain
application/json
text/xml
application/xml

Delete Job

https://job-sheduling.info/1/jobs/<id>

Deletes an existing one-time or recurring job.

Version1
MethodDELETE
Parametersid - the id of the job to delete
Request FormatsNone
Response FormatsNone

Create One-time Job

https://job-sheduling.info/1/jobs/<when>/<callback>

Alternative API call for creating a new one-time job which does not require building a request document. The time and callback URL are encoded in the request path, and the callback payload may optionally be included as the message body. If a payload in included, the Content-Type and X-Content-Signature request headers are copied to the corresponding fields describing the callback payload. See an example text, JSON or XML response.

ex. https://job-sheduling.info/1/jobs/2011-05-11T15%3A30%3A00Z/https%3A%2F%2Fexample.com

Version1
MethodPOST
Parameters when - URL encoded ISO8601 date to fire the job
callback - URL encoded callback URL
Request FormatsNone
Request Headers Content-Type - Optional content-type of the payload (optionally) included in the request body
X-Content-Signature - Optional signature for use in verifying the payload content on callback
Response Formats text/plain
application/json
text/xml
application/xml

Create Recurring Job

https://job-sheduling.info/1/jobs/<cron>/<callback>

Alternative API call for creating a new recurring job which does not require building a request document. The cron expression and callback URL are encoded in the request path, and the callback payload may optionally be included as the message body. If a payload in included, the Content-Type and X-Content-Signature request headers are copied to the corresponding fields describing the callback payload. See an example text, JSON or XML response.

ex. https://job-sheduling.info/1/jobs/0+15+10+%3F+*+*/https%3A%2F%2Fexample.com

Version1
MethodPOST
Parameters cron - URL encoded cron expression describing the firing schedule for the job
callback - URL encoded callback URL
Request Headers Content-Type - Optional content-type of the payload (optionally) included in the request body
X-Content-Signature - Optional signature for use in verifying the payload content on callback
Request FormatsNone
Response Formats text/plain
application/json
text/xml
application/xml


Example Documents

These are examples of formatted request and response documents:


Example JSON Request Document for a Recurring Job

{
  "url": "https://example.com/my-callback",
  "cron": "0 15 10 ? * *",
}

Example JSON Request Document for a Single Job (with optional fields)

{
  "url": "https://example.com/my-callback",
  "signature": "507aaa0733464499847c930db95983f8994ae266",
  "contentType": "text/plain",
  "data": "testing",
  "when": "2011-05-11T15:30:00Z"
}

Example JSON Response Document for a Recurring Job

{
  "id": "03ba07bc-0c8b-4a82-9a47-c65e7a8d24af"
  "account": "example"
  "url": "https://example.com/my-callback",
  "cron": "0 15 10 ? * *",
  "next": "2011-05-11T15:30:00Z"
}

Example JSON Response for a Single Job (with optional fields)

{
  "id": "03ba07bc-0c8b-4a82-9a47-c65e7a8d24af"
  "account": "example"
  "url": "https://example.com/my-callback",
  "signature": "507aaa0733464499847c930db95983f8994ae266",
  "contentType": "text/plain",
  "data": "testing",
  "when": "2011-05-11T15:30:00Z"
}

Example XML Request Document for a Recurring Job

<job>
  <url>https://example.com/my-callback</url>
  <cron>0 15 10 ? * *</cron>
</job>

Example XML Request Document for a Single Job (with optional fields)

<job>
  <url>https://example.com/my-callback</url>
  <signature>507aaa0733464499847c930db95983f8994ae266</signature>
  <contentType>text/plain</contentType>
  <data>testing</data>
  <when>2011-05-11T15:30:00Z</when>
</job>

Example XML Response Document for a Recurring Job

<job>
  <id>03ba07bc-0c8b-4a82-9a47-c65e7a8d24af</id>
  <account>example</account>
  <url>https://example.com/my-callback</url>
  <cron>0 15 10 ? * *</cron>
  <next>2011-05-11T15:30:00Z</next>
</job>

Example XML Response for a Single Job (with optional fields)

<job>
  <id>03ba07bc-0c8b-4a82-9a47-c65e7a8d24af</id>
  <account>example</account>
  <url>https://example.com/my-callback</url>
  <signature>507aaa0733464499847c930db95983f8994ae266</signature>
  <contentType>text/plain</contentType>
  <data>testing</data>
  <when>2011-05-11T15:30:00Z</when>
</job>

Example Plain Text Response for Job Create

03ba07bc-0c8b-4a82-9a47-c65e7a8d24af

Example Plain Text Response for Job List

1,2,3

Example JSON Response for Job List

["1","2","3"]

Example XML Response for Job List

<jobs>
  <id>1</id>
  <id>2</id>
  <id>3</id>
</jobs>