> For the complete documentation index, see [llms.txt](https://docs.vagon.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vagon.io/teams/reference/preloaded-files.md).

# Preloaded Files

## List Preloaded Files

> Returns every file in the organization's \*\*preloaded-files pool\*\*, newest first.\
> \
> Preloaded files are switched on per organization from the backoffice; while off, every route\
> under this tag answers \`4235\`.\
> \
> A preloaded file is uploaded once into the pool and then \*\*linked\*\* to any number of the\
> organization's machines (\`POST /machines/{id}/preloaded-files/link\`). Each linked machine\
> copies the file to \`Desktop\Preloaded Files\` (Windows: \`C:\Users\Administrator\Desktop\Preloaded Files\`,\
> Linux: \`/home/ubuntu/Desktop/Preloaded Files\`) when its next session starts. While the copy\
> runs the machine reports \`friendly\_status: preparing\_files\` and cannot be connected to.\
> \
> \`upload\_status\` is \`success\` once the upload is complete, \`pending\` while it is in progress\
> and \`failed\` when the upload was never completed (an upload has 6 hours). Only files with\
> \`upload\_status: success\` can be linked. \`linked\_machine\_count\` is the number of machines the\
> file is currently linked to.\
> \
> \### Headers\
> \
> \| Name | Type |\
> \| --- | --- |\
> \| Authorization\\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |

```json
{"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.15"},"servers":[{"url":"https://api.vagon.io/organization-management/v1"}],"paths":{"/preloaded-files":{"get":{"summary":"List Preloaded Files","responses":{"200":{"description":"The organization's preloaded-files pool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListPreloadedFilesResponse"}}}},"4235":{"description":"Preloaded files are not enabled for this organization (switched on from the backoffice)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4235Response"}}}},"4710":{"description":"Permission required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4710Response"}}}}},"tags":["Preloaded Files"],"description":"Returns every file in the organization's **preloaded-files pool**, newest first.\n\nPreloaded files are switched on per organization from the backoffice; while off, every route\nunder this tag answers `4235`.\n\nA preloaded file is uploaded once into the pool and then **linked** to any number of the\norganization's machines (`POST /machines/{id}/preloaded-files/link`). Each linked machine\ncopies the file to `Desktop\\Preloaded Files` (Windows: `C:\\Users\\Administrator\\Desktop\\Preloaded Files`,\nLinux: `/home/ubuntu/Desktop/Preloaded Files`) when its next session starts. While the copy\nruns the machine reports `friendly_status: preparing_files` and cannot be connected to.\n\n`upload_status` is `success` once the upload is complete, `pending` while it is in progress\nand `failed` when the upload was never completed (an upload has 6 hours). Only files with\n`upload_status: success` can be linked. `linked_machine_count` is the number of machines the\nfile is currently linked to.\n\n### Headers\n\n| Name | Type |\n| --- | --- |\n| Authorization\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |"}}},"components":{"schemas":{"ListPreloadedFilesResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"files":{"type":"array","items":{"$ref":"#/components/schemas/PreloadedFile"}}}}]},"BaseResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"PreloadedFile":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"attributes":{"type":"object","properties":{"name":{"type":"string"},"size":{"type":"integer","description":"Size in bytes"},"upload_status":{"type":"string","enum":["success","pending","failed"]},"created_at":{"type":"string","format":"date-time"},"linked_machine_count":{"type":"integer","description":"Machines the file is currently linked to (list endpoint only)"}}}}},"Error4235Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"ErrorResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error4710Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]}}}}
```

## Create Preloaded File (Start Upload)

> Adds a file to the pool and returns presigned S3 upload URLs. Upload the file body with\
> \`PUT\` to the URL(s), then call \`POST /preloaded-files/{id}/complete\`.\
> \
> Files up to \*\*250 MB\*\* get a single URL. Larger files get one URL per 250 MB chunk\
> (\`chunk\_size\`, in MB); upload each chunk in order with \`PUT\`, keep the \`ETag\` response header\
> of every part, and pass them to \`complete\`. The URLs are valid for \*\*6 hours\*\*; an upload not\
> completed by then is discarded.\
> \
> \`name\` must be a bare file name (no path separators); it is unique inside the pool, and it is\
> the name the file gets on every linked machine's desktop.\
> \
> \### Headers\
> \
> \| Name | Type |\
> \| --- | --- |\
> \| Authorization\\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\
> \| Content-Type | application/json |\
> \
> \### Body\
> \
> \| Name | Type | Description |\
> \| --- | --- | --- |\
> \| name\\\* | string | File name, as it will appear on the desktop |\
> \| size\\\* | integer | File size in bytes |

```json
{"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.15"},"servers":[{"url":"https://api.vagon.io/organization-management/v1"}],"paths":{"/preloaded-files":{"post":{"summary":"Create Preloaded File (Start Upload)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePreloadedFileRequest"}}}},"responses":{"200":{"description":"Upload URLs for the new file","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePreloadedFileResponse"}}}},"400":{"description":"Invalid name or size","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}}},"4224":{"description":"A preloaded file with that name already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4224Response"}}}},"4228":{"description":"Preloaded file size exceeds the maximum allowed size (50 GB)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4228Response"}}}},"4235":{"description":"Preloaded files are not enabled for this organization (switched on from the backoffice)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4235Response"}}}},"4710":{"description":"Permission required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4710Response"}}}}},"tags":["Preloaded Files"],"description":"Adds a file to the pool and returns presigned S3 upload URLs. Upload the file body with\n`PUT` to the URL(s), then call `POST /preloaded-files/{id}/complete`.\n\nFiles up to **250 MB** get a single URL. Larger files get one URL per 250 MB chunk\n(`chunk_size`, in MB); upload each chunk in order with `PUT`, keep the `ETag` response header\nof every part, and pass them to `complete`. The URLs are valid for **6 hours**; an upload not\ncompleted by then is discarded.\n\n`name` must be a bare file name (no path separators); it is unique inside the pool, and it is\nthe name the file gets on every linked machine's desktop.\n\n### Headers\n\n| Name | Type |\n| --- | --- |\n| Authorization\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\n| Content-Type | application/json |\n\n### Body\n\n| Name | Type | Description |\n| --- | --- | --- |\n| name\\* | string | File name, as it will appear on the desktop |\n| size\\* | integer | File size in bytes |"}}},"components":{"schemas":{"CreatePreloadedFileRequest":{"type":"object","required":["name","size"],"properties":{"name":{"type":"string"},"size":{"type":"integer","description":"Size in bytes"}}},"CreatePreloadedFileResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"file_id":{"type":"integer"},"upload_urls":{"type":"array","description":"One presigned PUT URL per chunk, in part order","items":{"type":"string"}},"chunk_size":{"type":"integer","description":"Chunk size in MB"}}}]},"BaseResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error400Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"ErrorResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error4224Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4228Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4235Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4710Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]}}}}
```

## Complete Preloaded File Upload

> Finalizes an upload started with \`POST /preloaded-files\`. For a multipart upload (more than\
> one upload URL), \`parts\` carries the \`ETag\` of every uploaded chunk with its 1-based\
> \`part\_number\`; for a single-URL upload omit \`parts\` (an empty array is accepted too). The\
> uploaded object's size must match the \`size\` given when the upload was started, otherwise\
> the file is discarded and \`4227\` is returned.\
> \
> \### Headers\
> \
> \| Name | Type |\
> \| --- | --- |\
> \| Authorization\\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\
> \| Content-Type | application/json |\
> \
> \### Path Parameters\
> \
> \| Name | Type | Description |\
> \| --- | --- | --- |\
> \| id\\\* | integer | Preloaded file ID |\
> \
> \### Body\
> \
> \| Name | Type | Description |\
> \| --- | --- | --- |\
> \| parts | array | Multipart uploads only: \`\[{ "part\_number": 1, "etag": "..." }, ...]\` |

```json
{"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.15"},"servers":[{"url":"https://api.vagon.io/organization-management/v1"}],"paths":{"/preloaded-files/{id}/complete":{"post":{"summary":"Complete Preloaded File Upload","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompletePreloadedFileRequest"}}}},"responses":{"200":{"description":"Upload completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreloadedFileResponse"}}}},"404":{"description":"Preloaded file not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404Response"}}}},"4227":{"description":"Upload could not be completed (multipart error or size mismatch); the file is discarded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4227Response"}}}},"4235":{"description":"Preloaded files are not enabled for this organization (switched on from the backoffice)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4235Response"}}}},"4710":{"description":"Permission required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4710Response"}}}}},"tags":["Preloaded Files"],"description":"Finalizes an upload started with `POST /preloaded-files`. For a multipart upload (more than\none upload URL), `parts` carries the `ETag` of every uploaded chunk with its 1-based\n`part_number`; for a single-URL upload omit `parts` (an empty array is accepted too). The\nuploaded object's size must match the `size` given when the upload was started, otherwise\nthe file is discarded and `4227` is returned.\n\n### Headers\n\n| Name | Type |\n| --- | --- |\n| Authorization\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\n| Content-Type | application/json |\n\n### Path Parameters\n\n| Name | Type | Description |\n| --- | --- | --- |\n| id\\* | integer | Preloaded file ID |\n\n### Body\n\n| Name | Type | Description |\n| --- | --- | --- |\n| parts | array | Multipart uploads only: `[{ \"part_number\": 1, \"etag\": \"...\" }, ...]` |"}}},"components":{"schemas":{"CompletePreloadedFileRequest":{"type":"object","properties":{"parts":{"type":"array","description":"Required for a multipart upload (more than one upload URL); omit it for a single-URL upload.","items":{"type":"object","properties":{"part_number":{"type":"integer"},"etag":{"type":"string"}}}}}},"PreloadedFileResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"file":{"$ref":"#/components/schemas/PreloadedFile"}}}]},"BaseResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"PreloadedFile":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"attributes":{"type":"object","properties":{"name":{"type":"string"},"size":{"type":"integer","description":"Size in bytes"},"upload_status":{"type":"string","enum":["success","pending","failed"]},"created_at":{"type":"string","format":"date-time"},"linked_machine_count":{"type":"integer","description":"Machines the file is currently linked to (list endpoint only)"}}}}},"Error404Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"ErrorResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error4227Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4235Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4710Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]}}}}
```

## Delete Preloaded File

> Removes the file from the pool and unlinks it from every machine. Each machine deletes its\
> desktop copy when its next session starts.\
> \
> \### Headers\
> \
> \| Name | Type |\
> \| --- | --- |\
> \| Authorization\\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\
> \
> \### Path Parameters\
> \
> \| Name | Type | Description |\
> \| --- | --- | --- |\
> \| id\\\* | integer | Preloaded file ID |

```json
{"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.15"},"servers":[{"url":"https://api.vagon.io/organization-management/v1"}],"paths":{"/preloaded-files/{id}":{"delete":{"summary":"Delete Preloaded File","responses":{"200":{"description":"File removed from the pool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponse"}}}},"404":{"description":"Preloaded file not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404Response"}}}},"4235":{"description":"Preloaded files are not enabled for this organization (switched on from the backoffice)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4235Response"}}}},"4710":{"description":"Permission required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4710Response"}}}}},"tags":["Preloaded Files"],"description":"Removes the file from the pool and unlinks it from every machine. Each machine deletes its\ndesktop copy when its next session starts.\n\n### Headers\n\n| Name | Type |\n| --- | --- |\n| Authorization\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\n\n### Path Parameters\n\n| Name | Type | Description |\n| --- | --- | --- |\n| id\\* | integer | Preloaded file ID |"}}},"components":{"schemas":{"BaseResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error404Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"ErrorResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error4235Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4710Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]}}}}
```

## Link Preloaded File to Machines

> The reverse of \`POST /machines/{id}/preloaded-files/link\`: links one pool file to one or\
> more machines, \*\*all or nothing\*\*. The two directions write the same links; use whichever\
> fits the call, for example this one to roll a file out to a group of machines. The file is\
> copied to each machine's desktop when its next session starts.\
> \
> \`unzip\_zip\_files\` applies to every link made by the call: the file is extracted into a\
> folder of the same name (without \`.zip\`) next to it on each machine, the zip itself stays.\
> It is only kept for a file whose name ends in \`.zip\`; on any other file it is ignored, not\
> refused, and every machine answers \`unzip\_zip\_files: false\`.\
> \
> An API secret scoped to \`machine\_ids\` must cover every machine in the body.\
> \
> \### Headers\
> \
> \| Name | Type |\
> \| --- | --- |\
> \| Authorization\\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\
> \| Content-Type | application/json |\
> \
> \### Path Parameters\
> \
> \| Name | Type | Description |\
> \| --- | --- | --- |\
> \| id\\\* | integer | Preloaded file ID |\
> \
> \### Body\
> \
> \| Name | Type | Description |\
> \| --- | --- | --- |\
> \| machine\_ids\\\* | array | Machine IDs |\
> \| unzip\_zip\_files | boolean | Extract the file on each machine (default \`false\`; ignored unless the name ends in \`.zip\`) |

```json
{"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.15"},"servers":[{"url":"https://api.vagon.io/organization-management/v1"}],"paths":{"/preloaded-files/{id}/link":{"post":{"summary":"Link Preloaded File to Machines","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkPreloadedFileMachinesRequest"}}}},"responses":{"200":{"description":"The machines the file was linked to, in the order given, each with the bytes now linked to it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkPreloadedFileMachinesResponse"}}}},"400":{"description":"machine_ids missing, empty or repeated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}}},"404":{"description":"File or one of the machines not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404Response"}}}},"4223":{"description":"The file would exceed one of the machines' 50 GB limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4223Response"}}}},"4225":{"description":"The file has not finished uploading","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4225Response"}}}},"4226":{"description":"The file is already linked to one of the machines","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4226Response"}}}},"4235":{"description":"Preloaded files are not enabled for this organization (switched on from the backoffice)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4235Response"}}}},"4710":{"description":"Permission required, or a machine in the body is outside the secret's machine scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4710Response"}}}}},"tags":["Preloaded Files"],"description":"The reverse of `POST /machines/{id}/preloaded-files/link`: links one pool file to one or\nmore machines, **all or nothing**. The two directions write the same links; use whichever\nfits the call, for example this one to roll a file out to a group of machines. The file is\ncopied to each machine's desktop when its next session starts.\n\n`unzip_zip_files` applies to every link made by the call: the file is extracted into a\nfolder of the same name (without `.zip`) next to it on each machine, the zip itself stays.\nIt is only kept for a file whose name ends in `.zip`; on any other file it is ignored, not\nrefused, and every machine answers `unzip_zip_files: false`.\n\nAn API secret scoped to `machine_ids` must cover every machine in the body.\n\n### Headers\n\n| Name | Type |\n| --- | --- |\n| Authorization\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\n| Content-Type | application/json |\n\n### Path Parameters\n\n| Name | Type | Description |\n| --- | --- | --- |\n| id\\* | integer | Preloaded file ID |\n\n### Body\n\n| Name | Type | Description |\n| --- | --- | --- |\n| machine_ids\\* | array | Machine IDs |\n| unzip_zip_files | boolean | Extract the file on each machine (default `false`; ignored unless the name ends in `.zip`) |"}}},"components":{"schemas":{"LinkPreloadedFileMachinesRequest":{"type":"object","required":["machine_ids"],"properties":{"machine_ids":{"type":"array","items":{"type":"integer"}},"unzip_zip_files":{"type":"boolean","default":false,"description":"Extract the file next to itself on every machine listed. Ignored unless the file name ends in .zip."}}},"LinkPreloadedFileMachinesResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"machines":{"type":"array","items":{"$ref":"#/components/schemas/PreloadedFileMachine"}}}}]},"BaseResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"PreloadedFileMachine":{"type":"object","description":"A machine as seen from one pool file. `id` is the machine ID.","properties":{"id":{"type":"string"},"type":{"type":"string"},"attributes":{"type":"object","properties":{"name":{"type":"string"},"os":{"type":"string","enum":["windows","linux"]},"sync_status":{"type":"string","enum":["pending","synced","failed"],"description":"The file's state on this machine's desktop"},"unzip_zip_files":{"type":"boolean","description":"Whether the sync extracts the file into a folder of the same name next to it on this machine"},"synced_at":{"type":"string","format":"date-time","nullable":true},"last_error":{"type":"string","nullable":true},"total_size":{"type":"integer","description":"Bytes now linked to this machine, this file included"},"linked_at":{"type":"string","format":"date-time"}}}}},"Error400Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"ErrorResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error404Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4223Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4225Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4226Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4235Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4710Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]}}}}
```

## Unlink Preloaded File from Machines

> The reverse of \`POST /machines/{id}/preloaded-files/unlink\`: unlinks one pool file from one\
> or more machines. The file stays in the pool and stays on each desktop until that machine's\
> next session start deletes it.\
> \
> \### Headers\
> \
> \| Name | Type |\
> \| --- | --- |\
> \| Authorization\\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\
> \| Content-Type | application/json |\
> \
> \### Path Parameters\
> \
> \| Name | Type | Description |\
> \| --- | --- | --- |\
> \| id\\\* | integer | Preloaded file ID |\
> \
> \### Body\
> \
> \| Name | Type | Description |\
> \| --- | --- | --- |\
> \| machine\_ids\\\* | array | Machine IDs |

```json
{"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.15"},"servers":[{"url":"https://api.vagon.io/organization-management/v1"}],"paths":{"/preloaded-files/{id}/unlink":{"post":{"summary":"Unlink Preloaded File from Machines","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreloadedFileMachineIdsRequest"}}}},"responses":{"200":{"description":"File unlinked from the machines","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponse"}}}},"400":{"description":"machine_ids missing, empty or repeated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}}},"404":{"description":"File not found, or it is not linked to one of the machines","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404Response"}}}},"4235":{"description":"Preloaded files are not enabled for this organization (switched on from the backoffice)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4235Response"}}}},"4710":{"description":"Permission required, or a machine in the body is outside the secret's machine scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4710Response"}}}}},"tags":["Preloaded Files"],"description":"The reverse of `POST /machines/{id}/preloaded-files/unlink`: unlinks one pool file from one\nor more machines. The file stays in the pool and stays on each desktop until that machine's\nnext session start deletes it.\n\n### Headers\n\n| Name | Type |\n| --- | --- |\n| Authorization\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\n| Content-Type | application/json |\n\n### Path Parameters\n\n| Name | Type | Description |\n| --- | --- | --- |\n| id\\* | integer | Preloaded file ID |\n\n### Body\n\n| Name | Type | Description |\n| --- | --- | --- |\n| machine_ids\\* | array | Machine IDs |"}}},"components":{"schemas":{"PreloadedFileMachineIdsRequest":{"type":"object","required":["machine_ids"],"properties":{"machine_ids":{"type":"array","items":{"type":"integer"}}}},"BaseResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error400Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"ErrorResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error404Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4235Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4710Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]}}}}
```

## List Machine Preloaded Files

> Returns the pool files linked to the machine. \`sync\_status\` is the file's state on the\
> machine's desktop: \`pending\` until the next session start copies it, \`synced\` once it is\
> there (\`synced\_at\`), \`failed\` when the last copy did not finish (\`last\_error\`; retried at the\
> next session start). \`unzip\_zip\_files\` says whether the file is extracted next to itself on\
> this machine. \`total\_size\` is the sum of the linked files' sizes in bytes and \`limit\` the\
> per-machine ceiling (50 GB); extracted contents do not count toward either.\
> \
> \### Headers\
> \
> \| Name | Type |\
> \| --- | --- |\
> \| Authorization\\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\
> \
> \### Path Parameters\
> \
> \| Name | Type | Description |\
> \| --- | --- | --- |\
> \| id\\\* | integer | Machine ID |

```json
{"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.15"},"servers":[{"url":"https://api.vagon.io/organization-management/v1"}],"paths":{"/machines/{id}/preloaded-files":{"get":{"summary":"List Machine Preloaded Files","responses":{"200":{"description":"Files linked to the machine with their sync state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListMachinePreloadedFilesResponse"}}}},"404":{"description":"Machine not found or does not belong to the organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404Response"}}}},"4235":{"description":"Preloaded files are not enabled for this organization (switched on from the backoffice)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4235Response"}}}},"4710":{"description":"Permission required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4710Response"}}}}},"tags":["Preloaded Files"],"description":"Returns the pool files linked to the machine. `sync_status` is the file's state on the\nmachine's desktop: `pending` until the next session start copies it, `synced` once it is\nthere (`synced_at`), `failed` when the last copy did not finish (`last_error`; retried at the\nnext session start). `unzip_zip_files` says whether the file is extracted next to itself on\nthis machine. `total_size` is the sum of the linked files' sizes in bytes and `limit` the\nper-machine ceiling (50 GB); extracted contents do not count toward either.\n\n### Headers\n\n| Name | Type |\n| --- | --- |\n| Authorization\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\n\n### Path Parameters\n\n| Name | Type | Description |\n| --- | --- | --- |\n| id\\* | integer | Machine ID |"}}},"components":{"schemas":{"ListMachinePreloadedFilesResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"files":{"type":"array","items":{"$ref":"#/components/schemas/MachinePreloadedFile"}},"total_size":{"type":"integer","description":"Sum of the linked files' sizes in bytes"},"limit":{"type":"integer","description":"Per-machine ceiling in bytes"}}}]},"BaseResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"MachinePreloadedFile":{"type":"object","description":"A pool file as seen from one machine. `id` is the preloaded file ID.","properties":{"id":{"type":"string"},"type":{"type":"string"},"attributes":{"type":"object","properties":{"name":{"type":"string"},"size":{"type":"integer","description":"Size in bytes"},"upload_status":{"type":"string","enum":["success","pending","failed"]},"sync_status":{"type":"string","enum":["pending","synced","failed"],"description":"State of the file on this machine's desktop"},"unzip_zip_files":{"type":"boolean","description":"Whether the sync extracts the file into a folder of the same name next to it. Only ever true for a .zip."},"synced_at":{"type":"string","format":"date-time","nullable":true},"last_error":{"type":"string","nullable":true},"linked_at":{"type":"string","format":"date-time"}}}}},"Error404Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"ErrorResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error4235Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4710Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]}}}}
```

## Link Preloaded Files to Machine

> Links one or more pool files to the machine, \*\*all or nothing\*\*: if any file cannot be\
> linked, nothing is linked and the matching error is returned. The files are copied to the\
> machine's desktop when its next session starts; linking while the machine is running does\
> not touch the running session.\
> \
> Each entry can ask for \`unzip\_zip\_files\`: the file is then extracted into a folder of the\
> same name (without \`.zip\`) next to it, the zip itself stays. The flag is only kept for a\
> file whose name ends in \`.zip\`; on any other file it is ignored, not refused, and the link\
> answers \`unzip\_zip\_files: false\`. An extraction that fails marks the link \`failed\` with the\
> reason in \`last\_error\`, the other files are not affected, and the next session start tries\
> again without downloading the zip anew. To change the flag of a linked file, unlink and link\
> it again.\
> \
> \### Headers\
> \
> \| Name | Type |\
> \| --- | --- |\
> \| Authorization\\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\
> \| Content-Type | application/json |\
> \
> \### Path Parameters\
> \
> \| Name | Type | Description |\
> \| --- | --- | --- |\
> \| id\\\* | integer | Machine ID |\
> \
> \### Body\
> \
> \| Name | Type | Description |\
> \| --- | --- | --- |\
> \| files\\\* | array | One object per file: \`file\_id\` (integer, required) and \`unzip\_zip\_files\` (boolean, default \`false\`) |

```json
{"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.15"},"servers":[{"url":"https://api.vagon.io/organization-management/v1"}],"paths":{"/machines/{id}/preloaded-files/link":{"post":{"summary":"Link Preloaded Files to Machine","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkMachinePreloadedFilesRequest"}}}},"responses":{"200":{"description":"The newly created links","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkMachinePreloadedFilesResponse"}}}},"400":{"description":"files missing, empty or repeated, a file_id that is not a positive integer, or an unzip_zip_files that is not a boolean","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}}},"404":{"description":"Machine or one of the files not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404Response"}}}},"4223":{"description":"Linking these files would exceed the machine's 50 GB limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4223Response"}}}},"4225":{"description":"One of the files has not finished uploading","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4225Response"}}}},"4226":{"description":"One of the files is already linked to this machine","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4226Response"}}}},"4235":{"description":"Preloaded files are not enabled for this organization (switched on from the backoffice)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4235Response"}}}},"4710":{"description":"Permission required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4710Response"}}}}},"tags":["Preloaded Files"],"description":"Links one or more pool files to the machine, **all or nothing**: if any file cannot be\nlinked, nothing is linked and the matching error is returned. The files are copied to the\nmachine's desktop when its next session starts; linking while the machine is running does\nnot touch the running session.\n\nEach entry can ask for `unzip_zip_files`: the file is then extracted into a folder of the\nsame name (without `.zip`) next to it, the zip itself stays. The flag is only kept for a\nfile whose name ends in `.zip`; on any other file it is ignored, not refused, and the link\nanswers `unzip_zip_files: false`. An extraction that fails marks the link `failed` with the\nreason in `last_error`, the other files are not affected, and the next session start tries\nagain without downloading the zip anew. To change the flag of a linked file, unlink and link\nit again.\n\n### Headers\n\n| Name | Type |\n| --- | --- |\n| Authorization\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\n| Content-Type | application/json |\n\n### Path Parameters\n\n| Name | Type | Description |\n| --- | --- | --- |\n| id\\* | integer | Machine ID |\n\n### Body\n\n| Name | Type | Description |\n| --- | --- | --- |\n| files\\* | array | One object per file: `file_id` (integer, required) and `unzip_zip_files` (boolean, default `false`) |"}}},"components":{"schemas":{"LinkMachinePreloadedFilesRequest":{"type":"object","required":["files"],"properties":{"files":{"type":"array","items":{"type":"object","required":["file_id"],"properties":{"file_id":{"type":"integer"},"unzip_zip_files":{"type":"boolean","default":false,"description":"Extract the file next to itself on the machine. Ignored unless the file name ends in .zip."}}}}}},"LinkMachinePreloadedFilesResponse":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"files":{"type":"array","items":{"$ref":"#/components/schemas/MachinePreloadedFile"}}}}]},"BaseResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"MachinePreloadedFile":{"type":"object","description":"A pool file as seen from one machine. `id` is the preloaded file ID.","properties":{"id":{"type":"string"},"type":{"type":"string"},"attributes":{"type":"object","properties":{"name":{"type":"string"},"size":{"type":"integer","description":"Size in bytes"},"upload_status":{"type":"string","enum":["success","pending","failed"]},"sync_status":{"type":"string","enum":["pending","synced","failed"],"description":"State of the file on this machine's desktop"},"unzip_zip_files":{"type":"boolean","description":"Whether the sync extracts the file into a folder of the same name next to it. Only ever true for a .zip."},"synced_at":{"type":"string","format":"date-time","nullable":true},"last_error":{"type":"string","nullable":true},"linked_at":{"type":"string","format":"date-time"}}}}},"Error400Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"ErrorResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error404Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4223Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4225Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4226Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4235Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4710Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]}}}}
```

## Unlink Preloaded Files from Machine

> Unlinks the given pool files from the machine. The desktop copies are deleted when the\
> machine's next session starts. The files stay in the pool.\
> \
> \### Headers\
> \
> \| Name | Type |\
> \| --- | --- |\
> \| Authorization\\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\
> \| Content-Type | application/json |\
> \
> \### Path Parameters\
> \
> \| Name | Type | Description |\
> \| --- | --- | --- |\
> \| id\\\* | integer | Machine ID |\
> \
> \### Body\
> \
> \| Name | Type | Description |\
> \| --- | --- | --- |\
> \| file\_ids\\\* | array | Preloaded file IDs to unlink |

```json
{"openapi":"3.0.0","info":{"title":"Vagon Computers API","version":"1.0.15"},"servers":[{"url":"https://api.vagon.io/organization-management/v1"}],"paths":{"/machines/{id}/preloaded-files/unlink":{"post":{"summary":"Unlink Preloaded Files from Machine","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachinePreloadedFileIdsRequest"}}}},"responses":{"200":{"description":"Files unlinked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponse"}}}},"400":{"description":"file_ids missing or empty","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}}},"404":{"description":"Machine not found, or one of the files is not linked to it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404Response"}}}},"4235":{"description":"Preloaded files are not enabled for this organization (switched on from the backoffice)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4235Response"}}}},"4710":{"description":"Permission required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error4710Response"}}}}},"tags":["Preloaded Files"],"description":"Unlinks the given pool files from the machine. The desktop copies are deleted when the\nmachine's next session starts. The files stay in the pool.\n\n### Headers\n\n| Name | Type |\n| --- | --- |\n| Authorization\\* | HMAC {key}:{signature}:{nonce}:{timestamp} |\n| Content-Type | application/json |\n\n### Path Parameters\n\n| Name | Type | Description |\n| --- | --- | --- |\n| id\\* | integer | Machine ID |\n\n### Body\n\n| Name | Type | Description |\n| --- | --- | --- |\n| file_ids\\* | array | Preloaded file IDs to unlink |"}}},"components":{"schemas":{"MachinePreloadedFileIdsRequest":{"type":"object","required":["file_ids"],"properties":{"file_ids":{"type":"array","items":{"type":"integer"}}}},"BaseResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error400Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"ErrorResponse":{"type":"object","properties":{"client_code":{"type":"integer"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Error404Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4235Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]},"Error4710Response":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"}]}}}}
```
