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

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

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

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

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-02-10T01:19:19.139Z",
        "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-02-10T01:19:19.139Z",
      "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

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 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
400	Bad request
404	Machine not found or does not belong to organization
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

Responses

200

List of files and folders

application/json

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-02-10T01:19:19.139Z",
        "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-02-10T01:19:19.139Z",
      "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

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

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.

Notes

• Either directory_id or file_ids must be provided (not both empty)

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

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

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

Error Responses

Status	Description
400	Bad request (e.g., both directory_id and file_ids empty, invalid IDs, feature not enabled)
404	Directory or files not found or do not belong to organization
4710	Permission required

Request Body Example

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

Success Response Fields

Field	Type	Description
url	String	Presigned S3 download URL (for single file download)
size	Integer	File size in bytes
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)

   • Get download URL when status is uploaded

4. Download URLs expire after 24 hours

Body

application/json

directory_idintegerOptional

Directory ID to download (for directory downloads)

file_idsinteger[]Optional

List of file IDs to download

Responses

200

Download link generated

application/json

400

Bad request

application/json

404

File or directory not found

application/json

4710

Permission required

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: 35

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

{
  "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)
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"
  },
  "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

Path parameters

idintegerRequired

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

Example: 123

Responses

200

Download status

application/json

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