Keep a task's changes in the real folder

POST

/tasks/{id}/keep

const url = 'http://127.0.0.1:7700/api/tasks/t3k9x2a1b2/keep';
const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url http://127.0.0.1:7700/api/tasks/t3k9x2a1b2/keep \
  --header 'Authorization: Bearer <token>'

Preview, owner only. For a done task that worked on the owner’s real folders: applies its changes, one file at a time, each replaced atomically. A kept file keeps the real file’s owner, group and mode; a new file takes the owner of the folder it lands in. Before each file is written, its old version is saved under BOX_HOME/timemachine/<id>/, so the Keep can be undone with POST /tasks/{id}/unkeep.

If the owner changed, created or deleted any of the same files since the task started, nothing is applied in any folder and the response lists the clashing paths. A file that cannot be written (a full disk, no permission) puts back the files already written and says which file and why. A folder the task removed is listed file by file; Keep removes those files, then the folder once it is empty, so a file the owner added there meanwhile stays. The task’s review becomes kept or conflict, and a keep event goes into the log.

Authorizations

deviceToken
accessToken

Parameters

Path Parameters

required

string

The task id.

Example

t3k9x2a1b2

Responses

200

The changes applied, or the conflicts that stopped them.

application/json

One of:

object
object

object

kept

required

Array<object>

object

path

required

Path inside the workspace.

string

change

required

string

Allowed values: added modified deleted

Examples

{
  "kept": [
    {
      "path": "intro.md",
      "change": "modified"
    }
  ]
}

{
  "conflicts": [
    "notes.md"
  ]
}

400

No such task, the task is not done or was already kept, or its workspace is not a real folder.

application/json

object

error

required

What went wrong

string

Example

{
  "error": "\"Fix the intro\" is still working; Keep is for when it is done."
}

403

The owner’s route, called by someone who is not the box’s own screen or a device paired as the owner.

application/json

object

error

required

What went wrong

string

Example

{
  "error": "only this computer's own screen or the owner's paired device can do this"
}