ArangoDB v3.10 reached End of Life (EOL) and is no longer supported.

This documentation is outdated. Please see the most recent stable version.

HTTP interface for tasks

The HTTP API for tasks lets you can manage the periodic or timed execution of server-side JavaScript code

List all tasks

GET /_api/tasks/

fetches all existing tasks on the server

Responses

200 OK
The list of tasks
- array of objects
  a list of all tasks
  command* string
  The JavaScript function for this task.
  created* number
  The timestamp when this task was created.
  database* string
  The database this task belongs to.
  id* string
  A string identifying the task.
  name* string
  A user-friendly name for the task.
  offset* number
  Time offset in seconds from the created timestamp.
  period* number
  This task should run each period seconds.
  type* string
  What type of task is this [ periodic, timed]
  periodic are tasks that repeat periodically
  timed are tasks that execute once at a specific time

Examples

Fetching all tasks

curl --header 'accept: application/json' --dump - http://localhost:8529/_api/tasks

Show output

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 2
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

[ ]

Get a task

GET /_api/tasks/{id}

fetches one existing task on the server specified by id

Path Parameters

id* string
The id of the task to fetch.

Query Parameters

HTTP Headers

Responses

200 OK
The requested task
- command* string
  The JavaScript function for this task.
- created* number
  The timestamp when this task was created.
- database* string
  The database this task belongs to.
- id* string
  A string identifying the task.
- name* string
  A user-friendly name for the task.
- offset* number
  Time offset in seconds from the created timestamp.
- period* number
  This task should run each period seconds.
- type* string
  What type of task is this [ periodic, timed]
  periodic are tasks that repeat periodically
  timed are tasks that execute once at a specific time

Examples

Fetching a single task by its id

curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/tasks
"{\"id\":\"testTask\",\"command\":\"console.log('Hello from task!');\",\"offset\":10000}"

curl --header 'accept: application/json' --dump - http://localhost:8529/_api/tasks/testTask

Show output

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 206
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "id" : "testTask", 
  "name" : "user-defined task", 
  "created" : 1712247110.3512406, 
  "type" : "timed", 
  "offset" : 10000, 
  "command" : "(function (params) { console.log('Hello from task!'); } )(params);", 
  "database" : "_system" 
}

Trying to fetch a non-existing task

curl --header 'accept: application/json' --dump - http://localhost:8529/_api/tasks/non-existing-task

Show output

HTTP/1.1 404 Not Found
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 73
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "code" : 404, 
  "error" : true, 
  "errorMessage" : "task not found", 
  "errorNum" : 1852 
}

Create a task

POST /_api/tasks

creates a new task with a generated id

Request Body application/json object

command* string
The JavaScript code to be executed
name* string
The name of the task
offset integer
Number of seconds initial delay
params* string
The parameters to be passed into command
period integer
number of seconds between the executions

Responses

200 OK
The task was registered
- code* number
  The status code, 200 in this case.
- command* string
  the javascript function for this task
- created* number
  The timestamp when this task was created
- database* string
  the database this task belongs to
- error* boolean
  false in this case
- id* string
  A string identifying the task
- offset* number
  time offset in seconds from the created timestamp
- period* number
  this task should run each period seconds
- type* string
  What type of task is this [ periodic, timed]
  periodic are tasks that repeat periodically
  timed are tasks that execute once at a specific time
400 Bad Request
If the post body is not accurate, a HTTP 400 is returned.

Examples

curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/tasks/
{
  "name": "SampleTask",
  "command": "(function(params) { require('@arangodb').print(params); })(params)",
  "params": {
    "foo": "bar",
    "bar": "foo"
  },
  "period": 2
}

curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/tasks/69073

Show output

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 240
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "id" : "69073", 
  "name" : "SampleTask", 
  "created" : 1712247110.3803697, 
  "type" : "periodic", 
  "period" : 2, 
  "offset" : 0, 
  "command" : "(function (params) { (function(params) { require('@arangodb').print(params); })(params) } )(params);", 
  "database" : "_system" 
}

Create a task with ID

PUT /_api/tasks/{id}

Registers a new task with the specified ID.

Not compatible with load balancers.

Path Parameters

id* string
The id of the task to create

Query Parameters

HTTP Headers

Request Body application/json object

command* string
The JavaScript code to be executed
name* string
The name of the task
offset integer
Number of seconds initial delay
params* string
The parameters to be passed into command
period integer
number of seconds between the executions

Responses

400 Bad Request
If the task id already exists or the rest body is not accurate, HTTP 400 is returned.

Examples

curl -X PUT --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/tasks/sampleTask
{
  "id": "SampleTask",
  "name": "SampleTask",
  "command": "(function(params) { require('@arangodb').print(params); })(params)",
  "params": {
    "foo": "bar",
    "bar": "foo"
  },
  "period": 2
}

Show output

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 241
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "id" : "sampleTask", 
  "name" : "SampleTask", 
  "created" : 1712247110.394075, 
  "type" : "periodic", 
  "period" : 2, 
  "offset" : 0, 
  "command" : "(function (params) { (function(params) { require('@arangodb').print(params); })(params) } )(params);", 
  "database" : "_system" 
}

Delete a task

DELETE /_api/tasks/{id}

Deletes the task identified by id on the server.

Path Parameters

id* string
The id of the task to delete.

Query Parameters

HTTP Headers

Responses

200 OK
If the task was deleted, HTTP 200 is returned.
- code* number
  The status code, 200 in this case.
- error* boolean
  false in this case
404 Not Found
If the task id is unknown, then an HTTP 404 is returned.
- code* number
  The status code, 404 in this case.
- error* boolean
  true in this case
- errorMessage* string
  A plain text message stating what went wrong.

Examples

Try to delete a non-existent task:

curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/tasks/NoTaskWithThatName

Show output

HTTP/1.1 404 Not Found
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 73
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "code" : 404, 
  "error" : true, 
  "errorMessage" : "task not found", 
  "errorNum" : 1852 
}

Remove existing task:

curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/tasks/SampleTask

Show output

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 26
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "error" : false, 
  "code" : 200 
}