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" : 1739624882.9304473,
"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 identifier.
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
The number of seconds for the initial delay.
params
string
The parameters to be passed to the command.
period
integer
The number of seconds between the executions.
Responses
200
OK
The task has been registered.
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 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" : "69846",
"name" : "SampleTask",
"created" : 1739624882.9589047,
"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
The number of seconds for the initial delay.
params
string
The parameters to be passed to the command.
period
integer
The number of seconds between the executions.
Responses
200
OK
The task has been registered.
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' <<'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" : 1739624882.9723566,
"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
}
