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
4710	Permission required

Response Fields

Field	Type	Description
content	Array	Array of file system content objects
content[].path	String	Full path of the file or folder
content[].name	String	File or folder name
content[].is_directory	Boolean	true if directory, false if file
client_code	Integer	Response code (200 for success)
message	String	Response message
timestamp	String	Response timestamp (ISO 8601)

Request Body Example

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

Response Example

{
    "content": [
        {
            "path": "C:\\Users\\Administrator",
            "name": "Administrator",
            "is_directory": true
        },
        {
            "path": "C:\\Users\\Public",
            "name": "Public",
            "is_directory": true
        }
    ],
    "client_code": 200,
    "message": "OK",
    "timestamp": "2026-02-04T11:55:10Z"
}

Path parameters

idintegerRequired

(Required) Machine ID

Example: 1

Body

application/json

pathstringOptional

Responses

200

File system content

application/json

client_codeintegerOptionalExample: 200

messagestringOptionalExample: OK

timestampstring · date-timeOptionalExample: 2026-02-05T10:10:22Z

400

Bad request (machine is not running)

application/json

404

Machine not found

application/json

4710

Permission required

application/json

post

/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"
}

{
  "client_code": 200,
  "message": "OK",
  "timestamp": "2026-02-05T10:10:22Z",
  "content": [
    {
      "path": "C:\\Users\\Administrator",
      "name": "Administrator",
      "is_directory": true
    }
  ]
}

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
400	Bad request
404	Parent folder not found
4710	Permission required

Response Fields

Field	Type	Description
files	Array	Array of file/folder objects
files[].id	String	File/folder ID
files[].type	String	Always "file"
files[].attributes.name	String	File or folder name
files[].attributes.size	Integer	File size in bytes. 0 for directories
files[].attributes.content_type	String	MIME type (e.g., "image/png") or "directory"
files[].attributes.region	String	AWS region where file is stored
files[].attributes.status	String	File status (e.g., "upload_completed")
files[].attributes.object_type	String	Type: "file", "directory", or "root"
files[].attributes.path	String	Full path of the file/folder. null for some files
files[].attributes.parent_id	Integer	Parent folder ID
files[].attributes.last_modified_date	String	ISO 8601 timestamp of last modification
files[].attributes.file_storage_size	Integer	Total file storage size (in bytes). null for non-root
files[].attributes.file_storage_usage	Integer	Used file storage (in bytes). null for non-root
files[].attributes.user	Object	User who owns the file (null if none)
files[].attributes.user.id	String	User UUID
files[].attributes.user.type	String	Always "user"
files[].attributes.user.attributes.email	String	User email
files[].attributes.user.attributes.name	String	User name
files[].attributes.machine_id	Integer	Machine ID the file belongs to (null for organization shared storage)
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 last page
client_code	Integer	Response code (200 for success)
message	String	Response message
timestamp	String	Response timestamp (ISO 8601)

Response Example

{
    "files": [
        {
            "id": "18093",
            "type": "file",
            "attributes": {
                "name": "example.zip",
                "size": 0,
                "content_type": "directory",
                "region": "dublin",
                "status": "upload_completed",
                "object_type": "directory",
                "path": "/example.zip",
                "parent_id": 5122,
                "last_modified_date": null,
                "file_storage_size": null,
                "file_storage_usage": null,
                "user": null,
                "machine_id": null
            }
        },
        {
            "id": "18088",
            "type": "file",
            "attributes": {
                "name": "Project Folder",
                "size": 0,
                "content_type": "directory",
                "region": "dublin",
                "status": "upload_completed",
                "object_type": "directory",
                "path": "/Project Folder",
                "parent_id": 5122,
                "last_modified_date": null,
                "file_storage_size": null,
                "file_storage_usage": null,
                "user": null,
                "machine_id": null
            }
        }
    ],
    "current": {
        "id": "5122",
        "type": "file",
        "attributes": {
            "name": "Teams Shared Folder",
            "size": 0,
            "content_type": "directory",
            "region": "dublin",
            "status": "upload_completed",
            "object_type": "root",
            "path": null,
            "parent_id": null,
            "last_modified_date": "2026-02-04T12:07:59.204Z",
            "file_storage_size": 26843545600,
            "file_storage_usage": 0,
            "user": null,
            "machine_id": null
        }
    },
    "count": 2,
    "page": 1,
    "next_page": null,
    "client_code": 200,
    "message": "OK",
    "timestamp": "2026-02-05T10:17:46Z"
}

Query parameters

parent_idstringOptional

(Optional) Parent folder ID. Empty = root folder

Example: string

pageintegerOptional

(Optional) Page number. Default: 1

Example: 1

per_pageintegerOptional

(Optional) Records per page. Default: 20

Example: 20

qstringOptional

(Optional) Search by file name

Example: string

Responses

200

List of files and folders

application/json

client_codeintegerOptionalExample: 200

messagestringOptionalExample: OK

timestampstring · date-timeOptionalExample: 2026-02-05T10:10:22Z

countintegerOptional

Total number of items

Example: 2

pageintegerOptional

Current page number

Example: 1

next_pageinteger · nullableOptional

Next page number (null if no more pages)

400

Bad request

application/json

404

Parent folder not found

application/json

4710

Permission required

application/json

get

/files

HTTPcURLJavaScriptPython

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

{
  "client_code": 200,
  "message": "OK",
  "timestamp": "2026-02-05T10:10:22Z",
  "files": [
    {
      "id": "18093",
      "type": "file",
      "attributes": {
        "name": "example.zip",
        "size": 0,
        "content_type": "directory",
        "region": "dublin",
        "status": "upload_completed",
        "object_type": "directory",
        "path": "/example.zip",
        "parent_id": 5122,
        "last_modified_date": "2026-05-07T17:58:47.646Z",
        "file_storage_size": 26843545600,
        "file_storage_usage": 0,
        "user": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "type": "user",
          "attributes": {
            "email": "text",
            "name": "text"
          }
        },
        "machine_id": 1
      }
    }
  ],
  "current": {
    "id": "5122",
    "type": "file",
    "attributes": {
      "name": "example.zip",
      "size": 0,
      "content_type": "directory",
      "region": "dublin",
      "status": "upload_completed",
      "object_type": "directory",
      "path": "/example.zip",
      "parent_id": 5122,
      "last_modified_date": "2026-05-07T17:58:47.646Z",
      "file_storage_size": 26843545600,
      "file_storage_usage": 0,
      "user": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "type": "user",
        "attributes": {
          "email": "text",
          "name": "text"
        }
      },
      "machine_id": 1
    }
  },
  "count": 2,
  "page": 1,
  "next_page": null
}

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
450	Storage full
451	File already exists (when overwrite=false)
4710	Permission required

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
client_code	Integer	Response code (200 for success)
message	String	Response message
timestamp	String	Response timestamp (ISO 8601)

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)
client_code	Integer	Response code (200 for success)
message	String	Response message
timestamp	String	Response timestamp (ISO 8601)

Request Body Example

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

Success Response Example (File)

{
  "id": 6731,
  "uid": "string",
  "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,
  "client_code": 200,
  "message": "OK",
  "timestamp": "2026-02-05T10:00:00Z"
}

Success Response Example (Directory)

{
  "id": 124,
  "uid": "def456-ghi789-jkl012",
  "upload_urls": null,
  "chunk_size": 250,
  "client_code": 200,
  "message": "OK",
  "timestamp": "2026-02-05T10:00:00Z"
}

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

file_namestringRequired

Name of the file or directory

object_typestring · enumRequired

Type of object to create

Possible values:

content_typestringOptional

MIME type of the file (required for files)

sizeintegerOptional

File size in bytes (required for files)

chunk_sizeintegerOptional

Chunk size for multipart upload in MB

overwritebooleanOptional

Whether to overwrite existing file with same name

parent_idintegerOptional

Parent folder ID (root folder if omitted)

Responses

200

File or directory created successfully

application/json

Response after initiating a file upload

idintegerOptional

File ID

Example: 6731

uidstringOptional

Unique identifier for the upload

Example: abc123-def456

chunk_sizeintegerOptional

Size of each chunk in MB

Example: 250

400

Bad request

application/json

404

Machine not found

application/json

450

Storage full

application/json

451

File already exists

application/json

4710

Permission required

application/json

post

/files

HTTPcURLJavaScriptPython

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

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

{
  "id": 6731,
  "uid": "abc123-def456",
  "upload_urls": [
    {
      "part_number": 1,
      "url": "https://vagon-storage.s3.amazonaws.com/uploads/part1?signature=abc123"
    }
  ],
  "chunk_size": 250
}

List Session Recordings Folder

get

Lists session recording files and folders. Same structure as GET /files but scoped to session recordings. Optionally filter by machine_id.

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
page	Integer	Page number. Default: 1
per_page	Integer	Records per page. Default: 20
q	String	Search query. Searches by file/directory name
machine_id	Integer	(Optional) Filter recordings by machine ID

Error Responses

Status	Description
400	Bad request
404	Not found
403	Forbidden
4710	Permission required

Response Fields

Same structure as GET /files. The response includes files, current, count, page, next_page, client_code, message, and timestamp fields.

Response Example

{
    "files": [
        {
            "id": "5911",
            "type": "file",
            "attributes": {
                "name": "rec-20260121-214832.log",
                "size": 14463,
                "content_type": "application/octet-stream",
                "region": "dublin",
                "status": "upload_completed",
                "object_type": "file",
                "path": "/Session_1950/rec-20260121-214832.log",
                "parent_id": 22086,
                "last_modified_date": "2026-01-21T21:49:09.491Z",
                "file_storage_size": null,
                "file_storage_usage": null,
                "user": null,
                "machine_id": null
            }
        },
        {
            "id": "5910",
            "type": "file",
            "attributes": {
                "name": "rec-20260121-214832.mp4",
                "size": 2095700,
                "content_type": "video/mp4",
                "region": "dublin",
                "status": "upload_completed",
                "object_type": "file",
                "path": "/Session_1950/rec-20260121-214832.mp4",
                "parent_id": 22086,
                "last_modified_date": "2026-01-21T21:49:09.203Z",
                "file_storage_size": null,
                "file_storage_usage": null,
                "user": null,
                "machine_id": null
            }
        }
    ],
    "current": {
        "id": "22086",
        "type": "file",
        "attributes": {
            "name": "Session_1950",
            "size": 0,
            "content_type": "directory",
            "region": "dublin",
            "status": "upload_completed",
            "object_type": "directory",
            "path": "/Session_1950",
            "parent_id": 22049,
            "last_modified_date": "2026-01-21T21:49:09.491Z",
            "file_storage_size": null,
            "file_storage_usage": null,
            "user": null,
            "machine_id": null
        }
    },
    "count": 2,
    "page": 1,
    "next_page": null,
    "client_code": 200,
    "message": "OK",
    "timestamp": "2026-02-16T10:21:33Z"
}

Query parameters

machine_idintegerOptional

(Optional) Filter session recordings by machine ID

Example: 1

parent_idstringOptional

(Optional) Parent folder ID. Empty = root folder

Example: string

pageintegerOptional

(Optional) Page number. Default: 1

Example: 1

per_pageintegerOptional

(Optional) Records per page. Default: 20

Example: 20

qstringOptional

(Optional) Search by file name

Example: string

Responses

200

List of session recording files and folders

application/json

client_codeintegerOptionalExample: 200

messagestringOptionalExample: OK

timestampstring · date-timeOptionalExample: 2026-02-05T10:10:22Z

countintegerOptional

Total number of items

Example: 2

pageintegerOptional

Current page number

Example: 1

next_pageinteger · nullableOptional

Next page number (null if no more pages)

400

Bad request

application/json

403

Forbidden

application/json

404

Not found

application/json

4710

Permission required

application/json

get

/files/recordings

HTTPcURLJavaScriptPython

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

{
  "client_code": 200,
  "message": "OK",
  "timestamp": "2026-02-05T10:10:22Z",
  "files": [
    {
      "id": "18093",
      "type": "file",
      "attributes": {
        "name": "example.zip",
        "size": 0,
        "content_type": "directory",
        "region": "dublin",
        "status": "upload_completed",
        "object_type": "directory",
        "path": "/example.zip",
        "parent_id": 5122,
        "last_modified_date": "2026-05-07T17:58:47.646Z",
        "file_storage_size": 26843545600,
        "file_storage_usage": 0,
        "user": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "type": "user",
          "attributes": {
            "email": "text",
            "name": "text"
          }
        },
        "machine_id": 1
      }
    }
  ],
  "current": {
    "id": "5122",
    "type": "file",
    "attributes": {
      "name": "example.zip",
      "size": 0,
      "content_type": "directory",
      "region": "dublin",
      "status": "upload_completed",
      "object_type": "directory",
      "path": "/example.zip",
      "parent_id": 5122,
      "last_modified_date": "2026-05-07T17:58:47.646Z",
      "file_storage_size": 26843545600,
      "file_storage_usage": 0,
      "user": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "type": "user",
        "attributes": {
          "email": "text",
          "name": "text"
        }
      },
      "machine_id": 1
    }
  },
  "count": 2,
  "page": 1,
  "next_page": null
}

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.

Pass task_id to filter the response to folders associated with a specific task — the task's output/snapshot folder plus all session recording folders that were active under that task. Only directories are returned at this level; clients descend via parent_id to enumerate folder contents.

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
task_id	Integer	No	Filter to folders associated with the given task on the machine. Returns the task's output/snapshot folder plus linked session recording folders. Directories only.

Error Responses

Status	Description
400	Bad request
404	Machine not found, does not belong to organization, or task_id does not belong to the machine
4710	Permission required

Response Fields

Field	Type	Description
files	Array	Array of file/folder objects
files[].id	String	File/folder ID
files[].type	String	Always "file"
files[].attributes.name	String	File or folder name
files[].attributes.size	Integer	File size in bytes. 0 for directories
files[].attributes.content_type	String	MIME type (e.g., "image/png") or "directory"
files[].attributes.region	String	AWS region where file is stored
files[].attributes.status	String	File status (e.g., "upload_completed")
files[].attributes.object_type	String	Type: "file", "directory", or "root"
files[].attributes.path	String	Full path of the file/folder. null for some files
files[].attributes.parent_id	Integer	Parent folder ID
files[].attributes.last_modified_date	String	ISO 8601 timestamp of last modification
files[].attributes.file_storage_size	Integer	Total file storage size for the machine (in bytes). null for non-root
files[].attributes.file_storage_usage	Integer	Used file storage for the machine (in bytes). null for non-root
files[].attributes.user	Object	User who owns the file
files[].attributes.user.id	String	User UUID
files[].attributes.user.type	String	Always "user"
files[].attributes.user.attributes.email	String	User email
files[].attributes.user.attributes.name	String	User name
files[].attributes.machine_id	Integer	Machine ID the file belongs to
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 last page
client_code	Integer	Response code (200 for success)
message	String	Response message
timestamp	String	Response timestamp (ISO 8601)

Response Example

{
    "files": [
        {
            "id": "18468",
            "type": "file",
            "attributes": {
                "name": "Machine Project Folder",
                "size": 0,
                "content_type": "directory",
                "region": "dublin",
                "status": "upload_completed",
                "object_type": "directory",
                "path": "/Machine Project Folder",
                "parent_id": 18465,
                "last_modified_date": "2026-02-05T10:20:53.650Z",
                "file_storage_size": null,
                "file_storage_usage": null,
                "user": {
                    "id": "f1592625-edd0-48df-9bc0-de14910ec936",
                    "type": "user",
                    "attributes": {
                        "email": "[email protected]",
                        "name": "Computer User"
                    }
                },
                "machine_id": 100
            }
        },
        {
            "id": "18473",
            "type": "file",
            "attributes": {
                "name": "image.png",
                "size": 303043,
                "content_type": "image/png",
                "region": "dublin",
                "status": "upload_completed",
                "object_type": "file",
                "path": null,
                "parent_id": 18465,
                "last_modified_date": "2026-02-05T10:20:33.331Z",
                "file_storage_size": null,
                "file_storage_usage": null,
                "user": {
                    "id": "f1592625-edd0-48df-9bc0-de14910ec936",
                    "type": "user",
                    "attributes": {
                        "email": "[email protected]",
                        "name": "Computer User"
                    }
                },
                "machine_id": 100
            }
        }
    ],
    "current": {
        "id": "18465",
        "type": "file",
        "attributes": {
            "name": "Computer #100",
            "size": 0,
            "content_type": "directory",
            "region": "dublin",
            "status": "upload_completed",
            "object_type": "root",
            "path": null,
            "parent_id": null,
            "last_modified_date": "2026-02-05T10:20:53.650Z",
            "file_storage_size": 26843545600,
            "file_storage_usage": 2688255,
            "user": {
                "id": "f1592625-edd0-48df-9bc0-de14910ec936",
                "type": "user",
                "attributes": {
                    "email": "[email protected]",
                    "name": "Computer User"
                }
            },
            "machine_id": 100
        }
    },
    "count": 3,
    "page": 1,
    "next_page": null,
    "client_code": 200,
    "message": "OK",
    "timestamp": "2026-02-05T10:22:33Z"
}

Path parameters

idintegerRequired

(Required) Machine ID

Example: 1

Query parameters

parent_idstringOptional

(Optional) Parent folder ID. Empty = root folder

Example: string

pageintegerOptional

(Optional) Page number. Default: 1

Example: 1

per_pageintegerOptional

(Optional) Records per page. Default: 20

Example: 20

qstringOptional

(Optional) Search by file name

Example: string

task_idintegerOptional

(Optional) Filter to folders associated with a specific task on the machine. Returns the task's output/snapshot folder, all session recording folders linked to this task. Only directories are returned; descend via parent_id to fetch contents.

Example: 42

Responses

200

List of files and folders

application/json

client_codeintegerOptionalExample: 200

messagestringOptionalExample: OK

timestampstring · date-timeOptionalExample: 2026-02-05T10:10:22Z

countintegerOptional

Total number of items

Example: 2

pageintegerOptional

Current page number

Example: 1

next_pageinteger · nullableOptional

Next page number (null if no more pages)

400

Bad request

application/json

404

Machine not found

application/json

4710

Permission required

application/json

get

/machines/{id}/files

HTTPcURLJavaScriptPython

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

{
  "client_code": 200,
  "message": "OK",
  "timestamp": "2026-02-05T10:10:22Z",
  "files": [
    {
      "id": "18093",
      "type": "file",
      "attributes": {
        "name": "example.zip",
        "size": 0,
        "content_type": "directory",
        "region": "dublin",
        "status": "upload_completed",
        "object_type": "directory",
        "path": "/example.zip",
        "parent_id": 5122,
        "last_modified_date": "2026-05-07T17:58:47.646Z",
        "file_storage_size": 26843545600,
        "file_storage_usage": 0,
        "user": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "type": "user",
          "attributes": {
            "email": "text",
            "name": "text"
          }
        },
        "machine_id": 1
      }
    }
  ],
  "current": {
    "id": "5122",
    "type": "file",
    "attributes": {
      "name": "example.zip",
      "size": 0,
      "content_type": "directory",
      "region": "dublin",
      "status": "upload_completed",
      "object_type": "directory",
      "path": "/example.zip",
      "parent_id": 5122,
      "last_modified_date": "2026-05-07T17:58:47.646Z",
      "file_storage_size": 26843545600,
      "file_storage_usage": 0,
      "user": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "type": "user",
        "attributes": {
          "email": "text",
          "name": "text"
        }
      },
      "machine_id": 1
    }
  },
  "count": 2,
  "page": 1,
  "next_page": null
}

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
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)
4710	Permission required

Request Body Example

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

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)
client_code	Integer	Response code (200 for success)
message	String	Response message
timestamp	String	Response timestamp (ISO 8601)

Success Response Example

{
  "uid": "string",
  "download_url": "https://s3.amazonaws.com/bucket/file?X-Amz-Signature=...&X-Amz-Expires=3600",
  "client_code": 200,
  "message": "OK",
  "timestamp": "2026-02-05T10:00:00Z"
}

Path parameters

idintegerRequired

(Required) File ID (returned from create endpoint)

Example: 123

Body

application/json

Responses

200

Upload completed successfully

application/json

Response after completing a multipart upload

uidstringOptional

Unique identifier of the uploaded file

Example: abc123-def456

download_urlstring · uriOptional

URL to download the uploaded file

Example: https://vagon-storage.s3.amazonaws.com/files/abc123-def456

400

Bad request

application/json

404

File not found

application/json

450

Storage limit exceeded

application/json

452

File size mismatch

application/json

4710

Permission required

application/json

post

/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\""
    }
  ]
}

{
  "uid": "abc123-def456",
  "download_url": "https://vagon-storage.s3.amazonaws.com/files/abc123-def456"
}

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
400	Bad request
404	File/directory not found or does not belong to organization
450	Attempted to delete root folder
4710	Permission required

Success Response

{
    "client_code": 200,
    "message": "OK",
    "timestamp": "2026-02-04T12:16:26Z"
}

Path parameters

idintegerRequired

(Required) File/Directory ID

Example: 123

Responses

200

File deleted successfully

application/json

client_codeintegerOptionalExample: 200

messagestringOptionalExample: OK

timestampstring · date-timeOptionalExample: 2026-02-05T10:10:22Z

400

Bad request

application/json

404

File not found

application/json

4710

Permission required

application/json

delete

/files/{id}

HTTPcURLJavaScriptPython

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

{
  "client_code": 200,
  "message": "OK",
  "timestamp": "2026-02-05T10:10:22Z"
}

Generate Download Link for File

post

Creates download link for files or directory contents to let users create download links.

This endpoint allows you to download single/multiple file(s)s or an entire directory.

• For single file downloads, it returns a direct download URL.

• For multiple files or directories, it returns a download ID that can be used to check the status.

Headers

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

Body Parameters

Parameter	Type	Required	Description
directory_id	Integer	No	Directory ID to download recursively. Zips the entire directory and all subdirectories
file_ids	Array[Integer]	No	Array of file IDs to be downloaded.
task_id	Integer	No	Task ID. Bundles the task's output folder and every session recording folder linked to that task (across seat and admin storage) into a single ZIP. Each input directory becomes a top-level subfolder in the archive named after the directory.

Notes

• Exactly one of directory_id, file_ids, or task_id must be provided. Sending more than one (or none) returns 4722.

• For single file downloads (one file_id), returns a direct download URL immediately

• For multiple files, directories, or task_id, returns a download_id that must be used with GET /files/downloads/:id to check status and get download URL

• Multiple file downloads, directory downloads, and task_id downloads require the organization to have multiple_file_download feature enabled

Error Responses

Status	Description
400	Bad request (e.g., invalid IDs)
404	Directory or files not found or do not belong to organization
4710	Permission required (multiple file download not enabled)
4717	Directory or file not found
4718	File count mismatch during download (requested files not found)
4719	Directory is empty or has no completed files
4720	Download URL generation failed
4722	None of directory_id, file_ids, task_id provided — or more than one provided (mutually exclusive)

Request Body Example

Provide exactly one of directory_id, file_ids, or task_id. Remove the unused fields before sending — they are shown together below for reference only and are mutually exclusive.

{
  "directory_id": 1,
  "file_ids": [2, 3],
  "task_id": 42
}

Success Response Fields

Field	Type	Description
url	String	Presigned S3 download URL (for single file download)
size	Integer	File size in bytes (single file). For multiple files or directory, total size in bytes of all files to be zipped
name	String	File name
content_type	String	MIME type of the file
download_id	Integer	Download ID (for multiple files/directory - use with GET /files/downloads/:id)
client_code	Integer	Response code (200 for success)
message	String	Response message
timestamp	String	Response timestamp (ISO 8601)

Success Response Example

When downloading a single file, returns direct download URL. When downloading multiple files or a directory, returns download ID.

{
  "url": "https://s3.amazonaws.com/bucket/file?X-Amz-Signature=...&X-Amz-Expires=3600",
  "size": 1601,
  "name": "string",
  "content_type": "string",
  "download_id": 5085,
  "client_code": 200,
  "message": "OK",
  "timestamp": "2026-02-05T10:00:00Z"
}

Usage Flow

1. Call this endpoint with directory_id or file_ids

2. If single file: Use the returned url directly to download

3. If multiple files/directory: Use the returned download_id with GET /files/downloads/:id to:

   • Check processing status (pending, processing, uploaded, failed, cancelled)

   • Get download URL when status is uploaded

4. Download URLs expire after 24 hours

Body

application/json

or

or

Responses

200

Download link generated

application/json

Response containing download link information

urlstring · uri · nullableOptional

Download URL (null if still processing)

Example: https://vagon-storage.s3.amazonaws.com/downloads/xyz789

sizeinteger · nullableOptional

File size in bytes

Example: 1601

namestring · nullableOptional

File name

Example: project-files.zip

content_typestring · nullableOptional

MIME type of the file

Example: application/zip

download_idinteger · nullableOptional

Download job ID for status tracking

Example: 5085

400

Bad request

application/json

404

File or directory not found

application/json

4710

Permission required

application/json

4717

Directory or file not found

application/json

4718

File count mismatch during download

application/json

4719

Directory is empty or has no completed files

application/json

4720

Download URL generation failed

application/json

4722

No files or directory provided for download

application/json

post

/files/download

HTTPcURLJavaScriptPython

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

{
  "directory_id": 1,
  "file_ids": [
    2,
    3
  ],
  "task_id": 42
}

{
  "url": "https://vagon-storage.s3.amazonaws.com/downloads/xyz789",
  "size": 1601,
  "name": "project-files.zip",
  "content_type": "application/zip",
  "download_id": 5085
}

Get Download Status

get

Retrieves the status and download URL for a file download.

This endpoint is used to check the processing status of a file created via POST /files/download. The file is created asynchronously, so you need to poll this endpoint until the status is uploaded.

Headers

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

Path Parameters

Parameter	Type	Required	Description
id	Integer	Yes	Temporary file ID (download_id returned from POST /files/download)

Status Values

Status	Description
pending	File creation is queued but not started
processing	File is being created
uploaded	File is ready for download
failed	File creation failed

Error Responses

Status	Description
400	Bad request
404	Temporary file not found, expired, or does not belong to organization
4710	Permission required

Response Fields

Field	Type	Description
id	String	Temporary file ID
type	String	Always "download"
attributes.status	String	Current status: pending, processing, uploaded, failed
attributes.download_url	String	Presigned S3 download URL. Only present when status is uploaded and generate_download_url is true. Valid for limited time (typically 1 hour)
attributes.expires_at	String	ISO 8601 timestamp when the temporary file will be deleted (typically 24 hours after creation)
attributes.size	Integer	Total size in bytes of the files or directory being zipped (nullable for older records)
client_code	Integer	Response code (200 for success)
message	String	Response message
timestamp	String	Response timestamp (ISO 8601)

Success Response

{
  "id": "string",
  "type": "download",
  "attributes": {
    "status": "uploaded",
    "download_url": "https://s3.amazonaws.com/bucket/temp_files/uuid/archive.zip?X-Amz-Signature=...&X-Amz-Expires=3600",
    "expires_at": "2021-01-21T16:09:09.461Z",
    "size": 1048576
  },
  "client_code": 200,
  "message": "OK",
  "timestamp": "2026-02-05T10:00:00Z"
}

Usage Flow

1. Call POST /files/download with directory_id or file_ids to get a download_id

2. Poll this endpoint with the download_id to check status

3. When status is uploaded, use the download_url to download the zip file

4. Temporary files expire after 24 hours

5. To cancel a pending download, use DELETE /files/downloads/:id

Path parameters

idintegerRequired

(Required) Temporary file ID (download_id returned from POST /files/download)

Example: 123

Responses

200

Download status

application/json

Download job status response

idstringOptionalExample: 12345

typestringOptionalExample: download

400

Bad request

application/json

404

Download not found

application/json

4710

Permission required

application/json

get

/files/downloads/{id}

HTTPcURLJavaScriptPython

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

{
  "id": "12345",
  "type": "download",
  "attributes": {
    "status": "uploaded",
    "download_url": "https://vagon-storage.s3.amazonaws.com/downloads/xyz789",
    "expires_at": "2026-02-05T12:00:00.000Z",
    "size": 1048576
  }
}

Abort Pending Download

delete

Aborts a pending or processing zip download. Use the same id (download_id) as returned from POST /files/download and used with GET /files/downloads/:id. When status is processing, the running job will stop and abort the S3 multipart upload.

Path Parameters

Parameter	Type	Required	Description
id	Integer	Yes	Temporary file ID (download_id from POST /files/download)

Notes

• Both pending and processing downloads can be aborted. If the download is already uploaded, failed, or cancelled, the API returns 4716.

• After abort, the temporary file is marked as cancelled and will not be processed.

Path parameters

idintegerRequired

(Required) Temporary file ID (download_id returned from POST /files/download)

Example: 123

Responses

200

Download aborted successfully

application/json

anyOptional

400

Bad request (e.g. download cannot be aborted)

application/json

404

Download not found or expired

application/json

4710

Permission required

application/json

4716

Download cannot be aborted (already uploaded or failed)

application/json

delete

/files/downloads/{id}

HTTPcURLJavaScriptPython

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

No content