Files

List Files & Folders in Computer

post

Lists the file system content of a running machine.

This endpoint allows you to browse the machine's file system remotely. It returns files and folders in the specified path.

Headers

Name	Type
Authorization*	HMAC {key}:{signature}:{nonce}:{timestamp}
Content-Type	application/json

Path Parameters

Parameter	Type	Required	Description
id	Integer	Yes	Machine ID

Body Parameters

Parameter	Type	Required	Description
path	String	Yes	Folder path to list. Must be Windows format with escaped backslashes (e.g., "C:\Users", "C:\Users\Documents")

Error Responses

Status	Description
400	Bad request (machine is not running)
404	Machine not found or does not belong to organization

Response Fields

Field	Type	Description
content	Array/Object	File system content structure. Format depends on machine's file system API response

Response Example

{
  "content": [
    {
      "name": "Documents",
      "type": "directory",
      "path": "C:\\Users\\Documents"
    },
    {
      "name": "file.txt",
      "type": "file",
      "path": "C:\\Users\\file.txt",
      "size": 1024
    }
  ]
}

Path parameters

idintegerRequired

(Required) Machine ID

Example: 1

Body

application/json

pathstring · uriOptional

Responses

post

/organization-management/v1/machines/{id}/list-content

HTTPcURLJavaScriptPython

POST /organization-management/v1/machines/{id}/list-content HTTP/1.1
Host: api.vagon.io
Content-Type: application/json
Accept: */*
Content-Length: 20

{
  "path": "C:\\Users"
}

List Shared Files & Folders in Vagon Files

get

Lists the files and folders in Organization Shared Folder.

This endpoint lists files stored in the organization's shared storage. These files are accessible to all organization members.

Headers

Name	Type
Authorization*	HMAC {key}:{signature}:{nonce}:{timestamp}
Content-Type	application/json

Query Parameters

Parameter	Type	Description
parent_id	Integer	Parent folder ID. Empty or 0 = root folder (organization's shared root folder)
page	Integer	Page number. Default: 1
per_page	Integer	Records per page. Default: 20
q	String	Search query. Searches by file/directory name

Error Responses

Status	Description
404	Parent folder not found
4110	Subscription not active

Response Fields

Same structure as "List Machine Files" endpoint. See that endpoint for detailed field descriptions.

Response Example

{
  "files": [
    {
      "id": 1,
      "name": "project-files",
      "size": null,
      "content_type": "directory",
      "uid": "abc123",
      "object_type": "directory",
      "path": "project-files",
      "parent_id": 0,
      "last_modified_date": "2024-01-15T10:00:00Z",
      "region": "dublin",
      "status": "upload_completed"
    },
    {
      "id": 2,
      "name": "document.pdf",
      "size": 1048576,
      "content_type": "application/pdf",
      "uid": "def456",
      "object_type": "file",
      "path": "document.pdf",
      "parent_id": 1,
      "last_modified_date": "2024-01-15T11:00:00Z",
      "region": "dublin",
      "status": "upload_completed"
    }
  ],
  "current": {
    "id": 0,
    "name": "Teams Shared Folder",
    "object_type": "directory",
    "uid": "root123"
  },
  "count": 45,
  "page": 1,
  "next_page": 2
}

Query parameters

parent_idstringOptional

(Optional) Parent folder ID. Empty = root folder

pageintegerOptional

(Optional) Page number. Default: 1

Example: 1

per_pageintegerOptional

(Optional) Records per page. Default: 20

Example: 20

qstringOptional

(Optional) Search by file name

Responses

get

/organization-management/v1/files

HTTPcURLJavaScriptPython

GET /organization-management/v1/files HTTP/1.1
Host: api.vagon.io
Accept: */*

Upload File & Create Directory

post

Creates a new file or directory and initiates multipart upload for files.

This endpoint creates a file or directory entry. For files, it also generates presigned S3 URLs for multipart upload.

Headers

Name	Type
Authorization*	HMAC {key}:{signature}:{nonce}:{timestamp}
Content-Type	application/json

Body Parameters

Parameter	Type	Required	Description
machine_id	Integer	No	Machine ID. If provided, file/folder is created in machine's storage. null = organization shared storage
file_name	String	Yes	File or directory name. Must be unique within the parent folder (unless overwrite=true)
object_type	String	Yes	Type: "file" or "directory"
content_type	String	Yes (files only)	MIME type for files (e.g., "application/pdf", "image/png", "text/plain"). Required when object_type is "file"
size	Integer	Yes (files only)	File size in bytes. Required when object_type is "file"
chunk_size	Integer	No	Chunk size in MB for multipart upload. Default: 250 MB. Only used for files
overwrite	Boolean	No	If true, overwrites existing file with same name. Default: false
parent_id	Integer	Yes	Parent folder ID. Use 0 for root folder (machine root if machine_id provided, organization root if machine_id is null)

Chunk Size Explanation

• Files larger than chunk_size are uploaded in multiple parts

• Default chunk size is 250 MB

• Smaller chunks: More reliable on slow/unstable networks, easier to retry failed parts

• Larger chunks: Fewer requests, faster upload for stable networks

• Each part is uploaded separately to S3, then combined

Error Responses

Status	Description
400	Bad request (e.g., invalid object_type, missing required fields, parent folder not found or deleted)
404	Machine not found
4110	Subscription not active
450	Storage full
451	File already exists (when overwrite=false)

Success Response Fields (File)

Field	Type	Description
id	Integer	File ID (use this in complete endpoint)
uid	String	Unique identifier for the file
upload_urls	Array	Array of presigned S3 URLs for multipart upload. Each URL is for one chunk
upload_urls[].part_number	Integer	Part number (starts from 1)
upload_urls[].url	String	Presigned S3 URL for uploading this part
chunk_size	Integer	Chunk size in MB used for upload

Success Response Fields (Directory)

Field	Type	Description
id	Integer	Directory ID
uid	String	Unique identifier for the directory
upload_urls	null	Always null for directories
chunk_size	Integer	Chunk size (not used for directories)

Success Response Example (File)

{
  "id": 123,
  "uid": "abc123-def456-ghi789",
  "upload_urls": [
    {
      "part_number": 1,
      "url": "https://s3.amazonaws.com/bucket/file?uploadId=xyz&partNumber=1&X-Amz-Signature=..."
    },
    {
      "part_number": 2,
      "url": "https://s3.amazonaws.com/bucket/file?uploadId=xyz&partNumber=2&X-Amz-Signature=..."
    }
  ],
  "chunk_size": 250
}

Success Response Example (Directory)

{
  "id": 124,
  "uid": "def456-ghi789-jkl012",
  "upload_urls": null,
  "chunk_size": 250
}

Upload Flow for Files

1. Call this endpoint to create file entry and get upload URLs

2. For each part in upload_urls:

   • Make PUT request to the URL with the file chunk data

   • Save the ETag header from the PUT response

3. Call POST /files/:id/complete with all part numbers and ETags to finalize upload

4. Directory creation is immediate (no upload needed)

Body

application/json

machine_idany | nullableOptional

file_namestringOptional

object_typestringOptional

content_typestringOptional

sizeintegerOptional

chunk_sizeintegerOptional

overwritebooleanOptional

parent_idintegerOptional

Responses

post

/organization-management/v1/files

HTTPcURLJavaScriptPython

POST /organization-management/v1/files HTTP/1.1
Host: api.vagon.io
Content-Type: application/json
Accept: */*
Content-Length: 165

{
  "machine_id": null,
  "file_name": "example.zip",
  "object_type": "file",
  "content_type": "application/zip",
  "size": 104857600,
  "chunk_size": 250,
  "overwrite": false,
  "parent_id": 1
}

List Individual Files & Folders in Vagon Files

get

Lists files and folders belonging to a specific machine.

This endpoint allows you to browse the machine's file storage. You can navigate through folders using the parent_id parameter.

Headers

Name	Type
Authorization*	HMAC {key}:{signature}:{nonce}:{timestamp}
Content-Type	application/json

Path Parameters

Parameter	Type	Required	Description
id	Integer	Yes	Machine ID

Query Parameters

Parameter	Type	Required	Description
parent_id	Integer	No	Parent folder ID. Empty or 0 = root folder (machine's root folder)
page	Integer	No	Page number. Default: 1
per_page	Integer	No	Records per page. Default: 20
q	String	No	Search query. Searches by file/directory name

Error Responses

Status	Description
404	Machine not found or does not belong to organization
4110	Subscription not active

Response Fields

Field	Type	Description
files	Array	Array of file/folder objects
files[].id	Integer	File/folder ID
files[].name	String	File or folder name. For root folders, shows user email or invitation email
files[].size	Integer	File size in bytes. null for directories
files[].content_type	String	MIME type (e.g., "application/pdf"). null for directories
files[].uid	String	Unique identifier for the file/folder
files[].object_type	String	Type: "file" or "directory"
files[].path	String	Full path of the file/folder
files[].parent_id	Integer	Parent folder ID. 0 for root folder
files[].last_modified_date	String	ISO 8601 timestamp of last modification
files[].region	String	AWS region where file is stored
files[].status	String	File status (e.g., "upload_completed", "pending_upload")
files[].file_storage_size	Integer	Total file storage size for the machine (in bytes)
files[].file_storage_usage	Integer	Used file storage for the machine (in bytes)
current	Object	Current directory object (same structure as file objects). null if at root
count	Integer	Total number of files/folders in current directory
page	Integer	Current page number
next_page	Integer	Next page number. null if this is the last page

Response Example

{
  "files": [
    {
      "id": 1,
      "name": "Documents",
      "size": null,
      "content_type": "directory",
      "uid": "abc123",
      "object_type": "directory",
      "path": "Documents",
      "parent_id": 0,
      "last_modified_date": "2024-01-15T10:00:00Z",
      "region": "dublin",
      "status": "upload_completed",
      "file_storage_size": 10737418240,
      "file_storage_usage": 5368709120
    },
    {
      "id": 2,
      "name": "document.pdf",
      "size": 1048576,
      "content_type": "application/pdf",
      "uid": "def456",
      "object_type": "file",
      "path": "document.pdf",
      "parent_id": 0,
      "last_modified_date": "2024-01-15T11:00:00Z",
      "region": "dublin",
      "status": "upload_completed",
      "file_storage_size": 10737418240,
      "file_storage_usage": 5368709120
    }
  ],
  "current": {
    "id": 0,
    "name": "[email protected]",
    "object_type": "directory",
    "uid": "root123"
  },
  "count": 45,
  "page": 1,
  "next_page": 2
}

Path parameters

idintegerRequired

(Required) Machine ID

Example: 1

Query parameters

parent_idstringOptional

(Optional) Parent folder ID. Empty = root folder

pageintegerOptional

(Optional) Page number. Default: 1

Example: 1

per_pageintegerOptional

(Optional) Records per page. Default: 20

Example: 20

qstringOptional

(Optional) Search by file name

Responses

get

/organization-management/v1/machines/{id}/files

HTTPcURLJavaScriptPython

GET /organization-management/v1/machines/{id}/files HTTP/1.1
Host: api.vagon.io
Accept: */*

Complete Upload

post

Completes the multipart upload process for a file.

After uploading all file chunks to the presigned S3 URLs, call this endpoint to finalize the upload and make the file available.

Headers

Name	Type
Authorization*	HMAC {key}:{signature}:{nonce}:{timestamp}
Content-Type	application/json

Path Parameters

Parameter	Type	Required	Description
id	Integer	Yes	File ID (returned from create endpoint)

Body Parameters

Parameter	Type	Required	Description
parts	Array	Yes	Array of uploaded parts with their ETags
parts[].part_number	Integer	Yes	Part number (must match the part_number from upload_urls, starts from 1)
parts[].etag	String	Yes	ETag value returned from S3 PUT response header. Must include quotes. Example: "d8e8fca2dc0f896fd7cb4cb0031ba249"

About ETags

• When you PUT a chunk to S3, the response includes an ETag header

• Save this ETag exactly as returned (including the quotes)

• ETag format: "hexadecimal-string" (quotes are part of the value)

• Each part_number must have a corresponding ETag

• Parts must be in order (part_number 1, 2, 3, etc.)

Error Responses

Status	Description
400	Bad request (e.g., invalid parts format, file not found)
404	File not found or does not belong to organization
4110	Subscription not active
450	Storage limit exceeded after upload completion (file is deleted)
452	File size mismatch - actual uploaded size doesn't match expected size (file is deleted)

Success Response Fields

Field	Type	Description
uid	String	Unique identifier for the file
download_url	String	Presigned S3 URL for downloading the file. Valid for limited time (typically 1 hour)

Success Response Example

{
  "uid": "abc123-def456-ghi789",
  "download_url": "https://s3.amazonaws.com/bucket/file?X-Amz-Signature=...&X-Amz-Expires=3600"
}

Path parameters

idintegerRequired

(Required) File ID (returned from create endpoint)

Example: 123

Body

application/json

Responses

post

/organization-management/v1/files/{id}/complete

HTTPcURLJavaScriptPython

POST /organization-management/v1/files/{id}/complete HTTP/1.1
Host: api.vagon.io
Content-Type: application/json
Accept: */*
Content-Length: 139

{
  "parts": [
    {
      "part_number": 1,
      "etag": "\"d8e8fca2dc0f896fd7cb4cb0031ba249\""
    },
    {
      "part_number": 2,
      "etag": "\"7cb4cb0031ba249d8e8fca2dc0f896fd\""
    }
  ]
}

Generate Download Link for a File

get

Generates a temporary presigned download URL for a file.

This endpoint creates a time-limited download URL that can be used to download the file directly from S3 without requiring authentication.

Headers

Name	Type
Authorization*	HMAC {key}:{signature}:{nonce}:{timestamp}
Content-Type	application/json

Path Parameters

Parameter	Type	Description
id*	Integer	File ID

Error Responses

Status	Description
404	File not found, not completed, or does not belong to organization
4110	Subscription not active

Response Fields

Field	Type	Description
url	String	Presigned S3 download URL. Valid for limited time (typically 1 hour)
size	Integer	File size in bytes
name	String	File name
content_type	String	MIME type of the file

Response Example

{
  "url": "https://s3.amazonaws.com/bucket/file?X-Amz-Signature=abc123...&X-Amz-Expires=3600",
  "size": 104857600,
  "name": "example.zip",
  "content_type": "application/zip"
}

Usage

• The returned url is a presigned S3 URL that can be used directly

• URL is valid for a limited time (typically 1 hour)

• You can:

  • Open the URL in a browser to download

  • Use it in an HTTP GET request with any HTTP client

  • Share it with users (they don't need authentication)

• The action is logged with file_downloaded action type

Path parameters

idintegerRequired

(Required) File ID

Example: 123

Responses

get

/organization-management/v1/files/{id}/download

HTTPcURLJavaScriptPython

GET /organization-management/v1/files/{id}/download HTTP/1.1
Host: api.vagon.io
Accept: */*

Delete File from Vagon Files

delete

Deletes a file or directory. When a directory is deleted, all files and subdirectories inside it are also deleted recursively. This action is irreversible.

Headers

Name	Type
Authorization*	HMAC {key}:{signature}:{nonce}:{timestamp}
Content-Type	application/json

Path Parameters

Parameter	Type	Required	Description
id	Integer	Yes	File or Directory ID

Deletion Process

• Files: Immediately marked as deleted and removed from S3

• Directories: Recursively deletes all child files and subdirectories

  • Deletion happens asynchronously via background job

  • All nested content is soft-deleted

  • S3 objects are removed

Error Responses

Status	Description
404	File/directory not found or does not belong to organization
4110	Subscription not active
450	Attempted to delete root folder

Success Response

{
    "client_code": 200,
    "message": "OK",
    "timestamp": "2026-01-15T15:14:09Z"
}

Path parameters

idintegerRequired

(Required) File/Directory ID

Example: 123

Responses

delete

/organization-management/v1/files/{id}

HTTPcURLJavaScriptPython

DELETE /organization-management/v1/files/{id} HTTP/1.1
Host: api.vagon.io
Accept: */*