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

This documentation is outdated. Please see the most recent version here: Latest Docs

HTTP tasks Interface

Following you have ArangoDB’s HTTP Interface for Tasks.

There are also some examples provided for every API action.

Fetch all tasks or one task

Retrieves all currently active server tasks

GET /_api/tasks/

fetches all existing tasks on the server

Responses

HTTP 200: The list of tasks

  • (array): a list of all tasks

Examples

Fetching all tasks

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

HTTP/1.1 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

[ 
  { 
    "id" : "66", 
    "name" : "user-defined task", 
    "created" : 1600270813.2099967, 
    "type" : "periodic", 
    "period" : 1, 
    "offset" : 0.000001, 
    "command" : "(function (params) { (function () {\n        require('@arangodb/foxx/queues/manager').manage();\n      })(params) } )(params);", 
    "database" : "_system" 
  } 
]

Fetch one task with id

Retrieves one currently active server task

GET /_api/tasks/{id}

Path Parameters

  • id (string, required): The id of the task to fetch.

fetches one existing task on the server specified by id

Responses

HTTP 200: The requested task

Examples

Fetching a single task by its id

shell> 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

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

HTTP/1.1 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
Show response body

Trying to fetch a non-existing task

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

HTTP/1.1 Not Found
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
Show response body

creates a task

creates a new task

POST /_api/tasks

Request Body

  • name (string, required): The name of the task

  • command (string, required): The JavaScript code to be executed

  • params (string, required): The parameters to be passed into command

  • period (integer, optional): number of seconds between the executions

  • offset (integer, optional): Number of seconds initial delay

creates a new task with a generated id

Responses

HTTP 200: The task was registered

  • id (string): A string identifying the task

  • created (number): The timestamp when this task was created

  • 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

  • period (number): this task should run each period seconds

  • offset (number): time offset in seconds from the created timestamp

  • command (string): the javascript function for this task

  • database (string): the database this task belongs to

  • code (number): The status code, 200 in this case.

  • error (boolean): false in this case

HTTP 400: If the post body is not accurate, a HTTP 400 is returned.

Examples

shell> 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

HTTP/1.1 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/tasks/70449
Show response body

creates a task with id

registers a new task with a pre-defined id; not compatible with load balancers

PUT /_api/tasks/{id}

Path Parameters

  • id (string, required): The id of the task to create

Request Body

  • name (string, required): The name of the task

  • command (string, required): The JavaScript code to be executed

  • params (string, required): The parameters to be passed into command

  • period (integer, optional): number of seconds between the executions

  • offset (integer, optional): Number of seconds initial delay

registers a new task with the specified id

Responses

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

Examples

shell> 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

HTTP/1.1 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
Show response body

deletes the task with id

deletes one currently active server task

DELETE /_api/tasks/{id}

Path Parameters

  • id (string, required): The id of the task to delete.

Deletes the task identified by id on the server.

Responses

HTTP 200: If the task was deleted, HTTP 200 is returned.

  • code (number): The status code, 200 in this case.

  • error (boolean): false in this case

HTTP 404: 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

trying to delete non existing task

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

HTTP/1.1 Not Found
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
Show response body

Remove existing Task

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

HTTP/1.1 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
Show response body
❮  User Management

© ArangoDB - the native multi-model NoSQL database