Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.

npm version Build Status Slack Status


Scheduling as a Service, based on Agenda

Assuming all job types could be thought of as REST endpoints, scheduling could be offered as a service. agenda-rest does just that, introduce a URL, name it, agenda-rest will call it on the times that you specify.


Install agenda-rest as a global package

npm install -g agenda-rest


To launch the agenda-rest server, use the command line interface specifying the database host name and the database name

agenda-rest --dbhost localhost --dbname agenda

Command Line Interface options

Options Description
-d, --dbname [optional] Name of the Mongo database, default is agenda
-h, --dbhost [optional] Mongo instance's IP or domain name, default is localhost
-u, --dburi [optional] Full Mongo connection string. If specified, will override --dbhost, --dbname
-p, --port [optional] agenda-rest server port, default is 4040
-k, --key [optional] x-api-key to be expected in headers. If not specified, access to agenda-rest server would be unauthenticated
-t, --timeout [optional] Timeout for request duration, default is 5000 ms
-a, --agenda_settings [optional] A JSON string containing additional agenda settings. For example '{ "processEvery": "30 seconds" }'


API Documentation

API Documentation (Postman Generated) available at

GET /api/job

Get a list of defined jobs

  • Method: GET

POST /api/job

Defines a new category of jobs

  • Method: POST
  • Data:
    name,           // New job type's name
    url,            // koa-router style url
    method,         // (optional) Request type, default: POST
    callback: {     // (optional) to call with response after invocation

PUT /api/job/:jobName

Updates definition of a job category

  • Method: PUT
  • Data: same as POST /api/job

DELETE /api/job/:jobName

Deletes job definition and cancels occurrences

  • Method: DELETE

POST /api/job/once & POST /api/job/every

Schedule a job for single or multiple occurrences

  • Method: POST
  • Data:
    name,           // Name of the type to create the instance from
    interval,       // Interval in which job should be invoked (human-interval, can also be a date string for 'once')
    data: {         // (optional) default: {}
        headers,    // Http headers, e.g. { Authorization: '<token>' }
        params,     // An object i.e. { param1: 'value1' } used to replace path parameters `` => `` notations in the job definition's url.
        query,      // An object i.e. { foo: 'bar', baz: 'qux' } used to create query parameters (
        body        // Accompanying data sent along the request
    options: { // (optional) Enables passing options to the `every` method in agenda as documented [here](
      timezone, // Specify the job execution timezone.
      skipImmediate // Don't execute job immidiatly default is `false`.

Callback, if present, would be invoked by the following object:

    data: {
        // passed data object, same as above
    response        // response from invocation

POST /api/job/now

Like once and every, though without interval. Executes the job now.

POST /api/job/cancel

Cancels (not to be confused with 'delete') any jobs matching the query

  • Method: POST
  • Data: Mongo query
  name: "foo"