Tasks

Tasks are long-running operations that some users may want to come back to, or leave running in the background.

Authentication

Connecting to the task endpoint doesn't require any special permissions. However, each task has a list of ACLs that you must have at least one of to connect to the task.

For example, even though you can connect, if you don't have the system:maintenance:read ACL, you won't be able to access any of the session/object cleanup tasks.

Connect

Connecting and listening to task is a multi-stage process. You can listen to more than one task on the same websocket connection.

Setting up

This is a GET endpoint that upgrades to a Websocket connection upon connection.

When you connect, you'll get a single message:

• unauthenticated: There was an error fetching the internal states of your websocket connection, and you won't be able to connect to any tasks.
• connect: You've connect successfully to the endpoint, and you can continue.

Connecting to a task

Once connected, you can send a message in the following format:

connect/{task id}

Where "task id" is the ID of the task you want to connect to. These task IDs are returned by several other endpoints, like import endpoints and task CRUD endpoints.

After you send that message, you'll be connected to the task.

At any point, Drop will send one of the following messages:

Error event: error/{task id}/{error title}/{error body}

This means something has gone wrong with the task, and you should show or handle the error.

If "error title" is "Unknown task", your task ID was invalid, or you do not have the necessary ACLs to access the task.

This is different from an error generated from a task. This error is from Drop itself, not the task.

Disconnect event: disconnect/{task id}

The task has ended, and you'll no longer recieve updates

Task message: { ... JSON object ... }

If the message isn't one of the two above ones, it'll be a stringified JSON object that represents a task message:

{
  "id": "...",
  "name": "My Task",
  "success": false,
  "progress": 34,
  "error": null,
  "log": [
    "... JSON object ...",
    "... JSON object ...",
    "... more JSON objects ...",
    "... yet another JSON object ..."
  ],
  "reset": false
};

Task message properties

Here's what they do:

Fetch all tasks

curl -G http://localhost:3000/api/v1/admin/task \
  -H "Authorization: Bearer {token}"

{
    "runningTasks": [],
    "historicalTasks": [
        {
            "id": "cleanup:invitations:2025-08-23T08:27:15.156Z",
            "taskGroup": "cleanup:invitations",
            "name": "Cleanup Invitations",
            "started": "2025-08-23T08:27:15.156Z",
            "ended": "2025-08-23T08:27:15.258Z",
            "success": true,
            "error": null,
            "progress": 100,
            "log": [
                "{\"level\":\"info\",\"time\":\"2025-08-23T08:27:15.257Z\",\"msg\":\"Cleaning invitations\"}",
                "{\"level\":\"info\",\"time\":\"2025-08-23T08:27:15.258Z\",\"msg\":\"Done\"}"
            ],
            "acls": [
                "system:maintenance:read"
            ]
        },
        {
            "id": "cleanup:sessions:2025-08-23T01:02:47.015Z",
            "taskGroup": "cleanup:sessions",
            "name": "Cleanup Sessions",
            "started": "2025-08-23T01:02:47.016Z",
            "ended": "2025-08-23T01:02:47.132Z",
            "success": true,
            "error": null,
            "progress": 100,
            "log": [
                "{\"level\":\"info\",\"time\":\"2025-08-23T01:02:47.116Z\",\"msg\":\"Cleaning up sessions\"}",
                "{\"level\":\"info\",\"time\":\"2025-08-23T01:02:47.132Z\",\"msg\":\"Done\"}"
            ],
            "acls": [
                "system:maintenance:read"
            ]
        },
    ],
    "dailyTasks": [
        "cleanup:invitations",
        "cleanup:sessions",
        "check:update"
    ],
    "weeklyTasks": [
        "cleanup:objects"
    ]
}

Execute scheduled task

curl -X POST http://localhost:3000/api/v1/admin/task \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d "{ ... }"

{
    "id": "..."
}

Scheduled tasks

This is an exhaustive list of all scheduled tasks, their descriptions, and their tasks groups on Drop instances. It may be out-of-date for new versions. Please file a report if you believe it is out-of-date.