API Documentation

Cron Job API Method: add

Introduction

Add a cron job.

Arguments

token (Required)

You API token. Check authentication section for details.

url (Required)

URL of the cron job. Maximum length is 1024 chars.

cron_expression (Required)

Cron expression that following the syntax defined at our Cron Expression page.

timezone_from (Optional)

Specify the timezone source used to calculate the executing times of the cron job. Allowed values:
1 use the timezone in your EasyCron account.
2 use the timezone in the cron job.
Default to 1.

timezone (Ignored if timezone_from == 1. Required if timezone_from == 2)

Timezone in the cron job. Allowed values:
TZ Timezones.

cron_job_name (Optional)

The name of your cron job. Maximum length is 100 chars.

description (Optional)

The description of your cron job. Maximum length is 1024 chars.

auth_user (Optional)

HTTP basic authentication user. Maximum length is 100 chars.

auth_pw (Optional)

HTTP basic authentication password. Maximum length is 100 chars.

custom_timeout (Optional)

The max allowed execution time (in second) of your cron job. Execeeding this time, your cron job will time out and be marked as "failed". Allowed values:
0 to your plan's default timeout.
Default to 0.

criterion (Optional)

The rules for considering if an execution of cron job succeeded or failed. Allowed values:
1 Consider execution succeeded when the HTTP code is 2xx.
2 Consider execution succeeded when the HTTP code is 2xx and the HTTP body messge matches success_regexp.
3 Consider execution failed when the HTTP code is 2xx and the HTTP body messge matches failure_regexp.
Default to 1.

success_regexp (Optional)

The regular expression to match when criterion is set to 2. When criterion is not 2, this argument will be ignored. Maximum length is 255 chars.

failure_regexp (Optional)

The regular expression to match when criterion is set to 3. When criterion is not 3, this argument will be ignored. Maximum length is 255 chars.

email_me (Optional)

Email notification setting of the cron job. Allowed values:
0: never send email notification.
1: send email if execution fails or returns to success from failure.
Default to 0.

sensitivity (optional)

Only after encountering this amount of failures, the failure notification email will get sent. Allowed values:
1 to 5.
Default to 1.

group_id (Optional)

Group ID of the cron job. You could find the group ID in the group pages.
If this argument equals to 0, the cron job doesn't belong to any group.
Default to 0.

http_method (Optional)

HTTP method that your cron job HTTP requests will use. e.g. POST. Valid methods include "GET", "POST", "HEAD", "PUT", "PATCH", "DELETE", "CONNECT", "OPTIONS" and "TRACE".
Default to GET.

http_headers (Optional)

HTTP headers that your cron job HTTP requests will use.

http_message_body (Optional)

The HTTP message body to send for HTTP method "POST", "PUT" and "PATCH". It contains variable-value pairs or JSON payload. e.g. param1=val1&param2=val2 or {"name":"John","age":30}. Maximum length is 1024 chars. This argument only take affect if HTTP method is set to "POST", "PUT" or "PATCH".

send_slack (Optional)

Slack notification setting of the cron job. Allowed values:
0: never send Slack notification.
1: send Slack notification if execution fails.
2: send Slack notification after each execution.
Default to 0.

slack_sensitivity (optional)

Only after encountering this amount of failures, the failure Slack notification will get sent. Allowed values:
1 to 5.
Default to 1.

slack_url (Optional. If augument "send_slack" equals 1 or 2, "slack_url" is required.)

URL that the Slack notification is sent to. Maximum length is 1024 chars.

wh (Optional)

Webhook notification setting of the cron job. Allowed values:
0: never send webhook notification.
1: send webhook if execution fails.
2: send webhook after each execution.
Default to 0.

wh_url (Optional. If augument "wh" equals 1 or 2, "wh_url" is required.)

URL that the webhook request is sent to. Maximum length is 1024 chars.

wh_http_method (Optional)

HTTP method that your cron job webhook requests will use. e.g. POST. Valid methods include "GET", "POST", "HEAD", "PUT", "PATCH", "DELETE", "CONNECT", "OPTIONS" and "TRACE".
Default to GET.

wh_data[] (Optional)

Information that your cron job webhook requests will send. Valid values include "CRON_JOB_ID", "CRON_JOB_NAME", "CRON_JOB_URL", "CRON_JOB_HTTP_STATUS_CODE", "CRON_JOB_EXECUTION_STATUS" and "CRON_JOB_EXECUTION_ERROR".
E.g. wh_data[]=CRON_JOB_ID&wh_data[]=CRON_JOB_NAME will cause webhook requests including the cron job ID and name information.

status (Optional)

Status of the cron job. Allowed values:
0: create a disabled cron job.
1: create an enabled cron job.
Default to 1.

https://www.easycron.com/rest/add?token=[token]&cron_expression=* * * * * *&url=http%3A%2F%2Fwww.domain.com%2Fsendemails

In above example, [token] should be replaced with the true token string. The example adds a cron job (calling http://www.domain.com/sendemails) which will run every minute.

{"status":"success","cron_job_id":"2107"}

Above example response is equal to the following array:

Array
(
    [status] => success
    [cron_job_id] => 2107
)

If you use an invalid token, you may receive following error response:

{"status":"error","error":{"code":"1","message":"Wrong API token."}}

The equal readable array is:

Array
(
    [status] => error
    [error] => Array
        (
            [code] => 1
            [message] => Wrong API token.
        )

)

If there is something wrong with the arguments, you may receive other errors:

code: 2

message: Cron job name is too long.

code: 3

message: The cron expression you entered is invalid or it cannot be matched in a realitic future.

code: 9

message: The value of "email me" field is not valid.

code: 10

message: You need to upgrade your plan first to send email notifcations.

code: 12

message: The execution interval cannot be lower than [mininmumMinuteInterval] minutes. You can upgrade your plan to a paid plan to remove this limit.

code: 13

message: The URL format is wrong.

code: 14

message: The domain is prohibited to be added by free user.

code: 23

message: You don't have enough EPDs to create the cron job.

code: 24

message: An error occurred when adding the cron job.

If you make too much API requests in one day, you may receive following error:

code: 26

message: You have exceeded your max daily API request limit.

code: 31

message: The value of "http_message_body" field is too long (longer than 1024).

code: 33

message: The URL is too long (longer than 1024).

code: 34

message: You need to upgrade your plan first to customize your HTTP method (to method other than "GET").

code: 35

message: You need to upgrade your plan first to customize your HTTP headers.

code: 36

message: The HTTP method you set is incorrect.

code: 37

message: The value of "HTTP headers" field is too long (longer than 10K).

code: 38

message: Invalid cron job group.

code: 39

message: Your plan has expired. Please renew your plan first.

code: 40

message: Your HTTP auth user is too long (longer than 100 chars).

code: 41

message: Your HTTP auth password is too long (longer than 100 chars).

code: 42

message: The value of "sensitivity" field is not valid.

code: 43

message: The value of "Cron job timeout" field is invalid.

code: 44

message: The value of "Cron job timeout" field cannot be longer than XXXX seconds (your plan's default timeout).

code: 45

message: The description is too long (longer than 1024).

code: 47

message: Invalid option for augument "wh".

code: 48

message: You need to upgrade to an Enterprise plan first to use "webhook" feature.

code: 49

message: You should add a webhook URL.

code: 50

message: Your webhook URL is invalid.

code: 51

message: Your webhook URL is too long (longer than 1024 chars).

code: 52

message: Invalid webhook HTTP method.

code: 53

message: Augument "wh_data" should be in array format (e.g. "wh_data[]").

code: 54

message: The domain is prohibited to be added.

code: 55

message: You need to upgrade your plan first to use the "output matching" feature.

code: 56

message: Success regular expression is too long (longger than 255 chars)

code: 57

message: Invalid success regular expression: ERROR_DESCRIPTION

code: 58

message: Failure regular expression is too long (longger than 255 chars)

code: 59

message: Invalid failure regular expression: ERROR_DESCRIPTION

code: 60

message: The timezone is invalid.

code: 61

message: Invalid option for augument "send_slack".

code: 62

message: You need to upgrade your plan first to send Slack notifications.

code: 63

message: You should add a Slack URL.

code: 64

message: Your Slack URL is invalid.

code: 65

message: Your Slack URL is too long (longer than 1024 chars).

code: 66

message: Invalid status.

code: 67

message: Invalid timezone_from.