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.
Examples
Fetching all tasks
curl --header 'accept: application/json' --dump - 'http://localhost:8529/_api/tasks'
Show outputHTTP/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.
Examples
Fetching a single task by its id
curl -X POST --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/tasks' <<'EOF'
{"id":"testTask","command":"console.log('Hello from task!');","offset":10000}
EOF
curl --header 'accept: application/json' --dump - 'http://localhost:8529/_api/tasks/testTask'
Show outputHTTP/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" : 1730311780.2074919,
"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 outputHTTP/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 id
Path Parameters
database-name*
string
The name of the database.
Request Body application/json object
command*
string
The JavaScript code to be executed
name*
string
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
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/' <<'EOF'
{
"name": "SampleTask",
"command": "(function(params) { require('@arangodb').print(params); })(params)",
"params": {
"foo": "bar",
"bar": "foo"
},
"period": 2
}
EOF
Show outputHTTP/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" : "69531",
"name" : "SampleTask",
"created" : 1730311780.2280695,
"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
Request Body application/json object
command*
string
The JavaScript code to be executed
name*
string
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' <<'EOF'
{
"id": "SampleTask",
"name": "SampleTask",
"command": "(function(params) { require('@arangodb').print(params); })(params)",
"params": {
"foo": "bar",
"bar": "foo"
},
"period": 2
}
EOF
Show outputHTTP/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" : 1730311780.2422664,
"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.
Responses
200
OK
If the task was deleted, HTTP 200 is returned.
404
Not Found
If the task id is unknown, then an HTTP 404 is returned.
Examples
Try to delete a non-existent task:
curl -X DELETE --header 'accept: application/json' --dump - 'http://localhost:8529/_api/tasks/NoTaskWithThatName'
Show outputHTTP/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 outputHTTP/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
}
