1.3.1 • Public • Published

    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"


    npm i agenda-rest

    DownloadsWeekly Downloads






    Unpacked Size

    54.1 kB

    Total Files


    Last publish


    • keyvan-m-sadeghi
    • omgimalexis
    • simison
    • gffajardo