Chronos Scheduler API

This API is in Alpha, pricing and usage limitations to be determined

An API for scheduling one time or reoccuring webhook requests in the future. This has a multitude of uses in a Beep Boop project like triggering reminders, digest messages, expirations and so on. Reoccuring schedules are specified in the cron syntax. At the designated time(s), Chronos will make an HTTP request described when you register the task with a custom URL, method, headers and body.

Expects project based token for authentication as described on the API page.


List Scheduled Tasks

Returns a paginated list of all scheduled tasks for a project. Only active scheduled tasks will produce new requests. Tasks where inactive = true are expired.

GET https://beepboophq.com/api/v1/chronos/tasks

Query Params:

  • inactive - boolean filter, true returns only inactive, false returns only active tasks - default is neither (returns both)
  • per_page - # of records to return per page - default and max is 100
  • page - Page to retrieve - default is 1

Response:

200 if successful

{
  "current_page": 1,
  "total_pages": 1,
  "total_results": 2,
  "results": [
    {
      "id": "N2FhNWM4ZjM0ZWIwNGY0NWE3Nzc0N2IzNDQwYjk3MWZ8MzcgMjIgMjcgMSA1IDIwMTc=",
      "project_id": "ab143ebd6f6440888c1d4879c5ea59a1",
      "schedule": "37 22 27 1 5 2017",
      "url": "http://requestb.in/xxxxxxx",
      "method": "POST",
      "payload": {
        "greeting": "hello",
        "list": [
          {
            "one": 1
          }
        ],
        "object": {
          "two": 2
        }
      },
      "headers": {
        "User-Agent": "Custom/1.0",
        "X-custom": "a custom value"
      },
      "expires": "2017-01-27T15:38:00-07:00",
      "begins": "2017-01-02T00:00:01-07:00",
      "created": "2017-01-01T21:08:49.339453-07:00",
      "inactive": false
    },
    {
      "id": "ZmVlNjBhNmFlYzAwNDdmOGJjYTc3MmM5ZDY0NTJhNzd8KiAqICogKiAqICo=",
      "project_id": "ab143ebd6f6440888c1d4879c5ea59a1",
      "schedule": "0 */2 * * * *",
      "url": "https://beepboophq.com/proxy/xxxx/ping",
      "method": "GET",
      "created": "2016-12-26T19:55:52.465629-07:00",
      "inactive": false
    }
  ]
}

Create Scheduled Task

Create a Scheduled Task.

POST https://beepboophq.com/api/v1/chronos/tasks

Payload:

You can describe the schedule of the task via the schedule param. It supports either a timestamp string, or a cron string if you need it to be reocurring. At the time(s) specified, an HTTP(S) request is made to the specified url with the method including optional headers and application/json payload.

  • url required : HTTP(S) URL for the resource to request when scheduled
  • schedule required : schedule in cron format (e.g. 0 */15 * * * *) or an RFC3339 timestamp in the future. Note, the cron is evaluated in GMT.
    • 2017-06-01T21:08:49-08:00 or 2017-06-02T04:08:49Z would run once at the specified time.
    • 0 * * * * * would run at the top of every hour
    • */15 * * * 1-5 * would run every 15 minutes Monday - Friday
  • method: HTTP method (GET [default], POST, PUT, DELETE)
  • headers: an object of key-value strings with any custom headers to pass along with the request
  • payload: the JSON payload that will be sent to the specified url as the body of a POST or PUT request
  • expires: an optional RFC3339 timestamp for when the schedule should expire, only valid for reocurring tasks since one time task schedules expire immediately after running
  • begins: an optional RFC3339 timestamp for when the schedule should begin, only valid for reocurring tasks.
  • timezone: IATA Timezone string (e.g. 'America/New_York'). If provided, a reoccuring chron schedule should be provided in this timezone and daylights saving time will be observed. If no timezone is provided, UTC is assumed.

Cron format for schedule property:

      ┌───────────── minute (0 - 59)
      │ ┌───────────── hour (0 - 23)
      │ │ ┌───────────── day of month (1 - 31)
      │ │ │ ┌───────────── month (1 - 12)
      │ │ │ │ ┌───────────── day of week (0 - 6) (Sunday to Saturday)
      │ │ │ │ │ ┌───────────── year (2016 - 9999)
      │ │ │ │ │ │
      │ │ │ │ │ │
      * * * * * *

Reoccuring example:

{
  "schedule": "0 8 * * 1-5 *",
  "url": "http://requestb.in/xxxxxxxx",
  "method": "POST",
  "headers": {
      "X-custom": "a custom value",
      "User-Agent": "Custom/1.0"
  },
  "payload": {
      "greeting": "hello",
      "list": [{
          "one": 1
      }],
      "object": {
          "two": 2
      }
  },
  "expires": "2017-06-01T00:00:00Z"
}

One time example:

{
  "schedule": "2017-01-27T15:37:00-07:00",
  "url": "http://beepboophq.com/proxy/xxxx/ping",
  "method": "GET"
}

Incidentally, "one time" schedules may be described in the cron format instead of as a timestamp if it is specific enough. Also, schedules without explicit expires property may expire on their own if the cron is specific enough, for example specifying the year as 2016.

Response:

201 if successful

{
  "id": "OWRiODQxYjFmZGE2NDE1YzgzMDA2ODMxMWViYjdjYmN8MzcgMjIgMjcgMSA1IDIwMTc=",
  "project_id": "ab143ebd6f6440888c1d4879c5ea59a1",
  "schedule": "37 22 27 1 5 2017",
  "url": "http://requestb.in/wxtavpwx",
  "method": "POST",
  "payload": {
    "greeting": "hello",
    "list": [
      {
        "one": 1
      }
    ],
    "object": {
      "two": 2
    }
  },
  "headers": {
    "User-Agent": "Custom/1.0",
    "X-custom": "a custom value"
  },
  "expires": "2017-01-27T22:38:00Z",
  "created": "2017-01-02T20:56:40.395918153-07:00"
}

Delete Scheduled Task

Deletes a Scheduled Task

DELETE https://beepboophq.com/api/v1/chronos/tasks/:id

Response:

200 if successful

Scheduled Task History

Returns the paginated call history for a scheduled task, sorted with most recent first.

GET https://beepboophq.com/api/v1/chronos/tasks/:id/history

Query Params:

  • per_page - # of records to return per page - default and max is 100
  • page - Page to retrieve - default is 1

Response:

200 if successful

{
  "current_page": 1,
  "total_pages": 6,
  "total_results": 599,
  "results": [
    {
      "id": "5e4652e51c6b4628af03363bbddd2186",
      "task_id": "ZmVlNjBhNmFlYzAwNDdmOGJjYTc3MmM5ZDY0NTJhNzd8KiAqICogKiAqICo=",
      "project_id": "ab143ebd6f6440888c1d4879c5ea59a1",
      "status_code": 200,
      "headers": {
        "Alt-Svc": "clear",
        "Cache-Control": "no-cache, no-store, must-revalidate",
        "Content-Type": "application/json",
        "Date": "Sat, 31 Dec 2016 00:50:00 GMT",
        "Expires": "0",
        "Pragma": "no-cache",
        "Vary": "Accept-Encoding",
        "Via": "1.1 google",
        "X-Client-Version": "1.1.0"
      },
      "body": "{\"Ok\":true,\"Messages\":[],\"Ref\":\"6297338\"}",
      "successful": true,
      "error": "",
      "duration": 34,
      "created": "2016-12-30T17:50:00.744345-07:00"
    },
    {
      "id": "a6c9051af6024becb00399611f9faa14",
      "task_id": "ZmVlNjBhNmFlYzAwNDdmOGJjYTc3MmM5ZDY0NTJhNzd8KiAqICogKiAqICo=",
      "project_id": "ab143ebd6f6440888c1d4879c5ea59a1",
      "status_code": 200,
      "headers": {
        "Alt-Svc": "clear",
        "Cache-Control": "no-cache, no-store, must-revalidate",
        "Content-Type": "application/json",
        "Date": "Sat, 31 Dec 2016 00:49:00 GMT",
        "Expires": "0",
        "Pragma": "no-cache",
        "Vary": "Accept-Encoding",
        "Via": "1.1 google",
        "X-Client-Version": "1.1.0"
      },
      "body": "{\"Ok\":true,\"Messages\":[],\"Ref\":\"6297338\"}",
      "successful": true,
      "error": "",
      "duration": 31,
      "created": "2016-12-30T17:49:00.692893-07:00"
    },
    ...
}

duration is measured in milliseconds