ArangoDB v3.13 is under development and not released yet. This documentation is not final and potentially incomplete.

HTTP interface for tasks

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

List all tasks

GET /_db/{database-name}/_api/tasks

fetches all existing tasks on the server

Path Parameters

database-name* string
The name of a database. Which database you use doesn’t matter as long as the user account you authenticate with has at least read access to this database.

Query Parameters

HTTP Headers

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 /_db/{database-name}/_api/tasks/{id}

fetches one existing task on the server specified by id

Path Parameters

database-name* string
The name of a database. Which database you use doesn’t matter as long as the user account you authenticate with has at least read access to this database.
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" : 1710183825.5176382, 
  "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 /_db/{database-name}/_api/tasks

Creates a new task with a generated identifier.

Path Parameters

database-name* string
The name of the database.

Query Parameters

HTTP Headers

Request Body application/json object

command* string
The JavaScript code to be executed.
name string (default: "user-defined task")
The name of the task.
offset integer (default: 0)
The number of seconds for the initial delay.
params
The value to be passed to the command. It can be of any type.
period integer
The number of seconds between the executions.

Responses

200 OK
The task has been registered.
- command* string
  The JavaScript code of 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
  The name of the task.
- offset* number
  The time offset in seconds from the created timestamp.
- period* number
  The task runs every period seconds.
- type* string
  Possible values: "periodic", "timed"
  The kind of the task:
  "periodic": The task repeats periodically
  "timed": The task executes once at a specific time
400 Bad Request
The task can’t be registered because the request is invalid.

Examples

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

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" : "68899", 
  "name" : "SampleTask", 
  "created" : 1729508852.9353266, 
  "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 /_db/{database-name}/_api/tasks/{id}

Registers a new task with the specified ID.

Not compatible with load balancers.

Path Parameters

database-name* string
The name of the database.
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 (default: 0)
The number of seconds for the initial delay.
params
The value to be passed to the command. It can be of any type.
period integer
The number of seconds between the executions.

Responses

200 OK
The task has been registered.
- command* string
  The JavaScript code of this task.
- created* number
  The timestamp when this task was created.
- database* string
  The database this task belongs to.
- id* string
  The user-provided string identifying the task.
- name* string
  The name of the task.
- offset* number
  The time offset in seconds from the created timestamp.
- period* number
  The task runs every period seconds.
- type* string
  Possible values: "periodic", "timed"
  The kind of the task:
  "periodic": The task repeats periodically
  "timed": The task executes once at a specific time
400 Bad Request
The task can’t be registered because the request is invalid.
409 Conflict
A task with the specified id already exists.

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: 245
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" : 1710183856.9092274, 
  "type" : "periodic", 
  "period" : 2, 
  "offset" : 0, 
  "command" : "(function (params) { (function(params) { require('@arangodb').print(params); })(params) } )(params);", 
  "database" : "_system" 
}

Delete a task

DELETE /_db/{database-name}/_api/tasks/{id}

Deletes the task identified by id on the server.

Path Parameters

database-name* string
The name of a database. Which database you use doesn’t matter as long as the user account you authenticate with has administrate access to this database.
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 
}