Uploading with the Agent

Adding files to the queue

POST /upload-requests adds files to the Agent's upload queue and answers with the upload requests that were created. A request needs the paths to upload, and can say where they should land:

filePaths

Paths to the files or folders to upload, on the machine the Agent runs on. A folder is uploaded with its structure recreated as collections.

destinationStorageId

Optional. The storage to upload to. Without it the storage selected in the Agent is used, and the request is refused if the user has not selected one.

destinationCollectionId

Optional. The collection to upload into. Without it the collection selected in the Agent is used. The Agent checks that the user may upload there.

Every upload added over the API creates a new asset. There is no way to ask for a new version of an existing asset, or for a format on one, and a target or targetAsset in the request body is accepted but ignored.

curl -X POST http://localhost:6286/upload-requests \
  -H 'Content-Type: application/json' \
  -d '{
    "filePaths": ["/Users/me/Movies/my_clip.mov"],
    "destinationCollectionId": "COLLECTION-ID"
  }'

{
  "objects": [
    {
      "id": "01JB3A...",
      "type": "file",
      "title": "my_clip.mov",
      "assetIds": ["01JB3B..."]
    }
  ]
}

Files added this way wait in the queue. Start them from the Agent, or over the API with PATCH /uploads/{id}.

An upload request is a file or a folder, named by its type, and the assetIds it lists are the ids of the upload items it created, one per file.

Following the progress

Requests are listed with GET /upload-requests and GET /upload-requests/{id}, and the items belonging to one request with GET /upload-requests/{id}/uploads. Individual uploads are listed with GET /uploads and GET /uploads/{id}.

An upload item carries the request it belongs to, any error, and the uploader state: the file's target path inside the destination collection, its size and mime type, what it is uploading to, the ids created in Iconik as the upload progresses, the status, and the parts once the upload has started.

curl http://localhost:6286/uploads/01JB3B...

{
  "id": "01JB3B...",
  "uploadRequestId": "01JB3A...",
  "state": {
    "id": "01JB3C...",
    "fileInfo": {"targetPath": "my_clip.mov", "size": 52428800, "mimeType": "video/quicktime"},
    "target": {"type": "newAsset"},
    "formatId": "FORMAT-ID",
    "fileSetId": "FILE-SET-ID",
    "fileId": "FILE-ID",
    "status": "UPLOADING",
    "chunks": [
      {"index": 0, "status": "COMPLETED", "start": 0, "size": 26214400, "uploaded": 26214400},
      {"index": 1, "status": "UPLOADING", "start": 26214400, "size": 26214400, "uploaded": 5242880}
    ]
  }
}

The status is one of WAITING, UPLOADING, COMPLETING, COMPLETED, PAUSED or FAILED, and each part is WAITING, UPLOADING, COMPLETED or FAILED. A failed upload carries an error with a message and one of the codes UPLOAD_FILE_FAILED, CLOSE_FILE_FAILED or GENERATE_KEYFRAMES_FAILED.

state.target is what the upload writes to, which for an upload added over the API is always a new asset. state.targetAsset is a deprecated duplicate of it, kept so integrations written before the rename keep working; read target in new code.

Starting, pausing and cancelling

PATCH /uploads/{id} changes the status of a single upload. Only UPLOADING, which starts or resumes it, and PAUSED are accepted; anything else is answered with 400.

curl -X PATCH http://localhost:6286/uploads/01JB3B... \
  -H 'Content-Type: application/json' \
  -d '{"state": {"status": "UPLOADING"}}'

DELETE /uploads/{id} cancels an upload and answers with 204.

POST /upload is the older name for POST /upload-requests. It still works and takes the same body, but it is deprecated and new integrations should use /upload-requests.