Upload Files to Application

POST

apps

{id}

files

upload

Upload Files to Application

curl --request POST \
  --url https://api.vertracloud.app/v1/apps/{id}/files/upload \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({})
};

fetch('https://api.vertracloud.app/v1/apps/{id}/files/upload', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.vertracloud.app/v1/apps/{id}/files/upload"

payload = {}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vertracloud.app/v1/apps/{id}/files/upload"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "response": {}
}

{
  "response": {
    "image_build": {
      "image_id": "img-abc123def456",
      "build_id": "bld-abc123def456"
    },
    "message": "The image is rebuilding. The application restarts when the build succeeds."
  }
}

When the application runs a custom Docker image, the upload is a commit that rebuilds the image, so an API key needs the images:write scope as well as apps:files.

string

required

The ID of the application to upload files to. If the application belongs to a workspace, pass its ID in the workspace_id query parameter.

string

If set to "true", the application will automatically restart after the upload completes.

string

The destination folder, relative to the application’s root. Leave it empty or omit it to upload to the root. A ZIP is extracted inside this folder, and a loose file is written to path/<filename>. Folders in the path are created if they don’t exist. Path segments such as .. are rejected.

string

If the application belongs to a workspace, the workspace’s ID. Members with an Owner, Admin or Developer role can use the file manager on a workspace app they don’t own; without this, only the app’s own owner can.

file

required

The file to upload — either a single loose file (written at its target path as-is) or a ZIP archive.A ZIP is extracted on top of the destination folder (path, or the application’s root): files it contains overwrite the matching paths, but files already on disk that aren’t in the ZIP are left untouched — it’s a merge, not a replace. Forbidden directories (node_modules, .git, .local, and similar) are stripped from the ZIP on the server before extraction, regardless of what the archive contains.Multipart upload is capped at 100 MB; a ZIP is also capped at 512 MB once decompressed.

string

An optional message for this upload, shown in the application’s deploy history. Up to 500 characters. Leading and trailing spaces are removed, and an empty value means no message.

string

Set to true to confirm that the change detaches an application that came from an open template (it stops receiving versions). Without it the request changes nothing and answers 409 TEMPLATE_DETACH_CONFIRMATION_REQUIRED. Ignored for other applications. See Detach from a template.

Response

object

The result of the upload.

Show Toggle object

object | null

Only for an application that runs a custom Docker image: the upload is a commit that rebuilds the image, with the files placed on top of the image’s current build context. Has image_id and build_id. null or absent for a regular application. See Custom Docker images.

string

A readable summary, for example that the image is rebuilding and the application restarts when the build succeeds.

{
  "response": {}
}

{
  "response": {
    "image_build": {
      "image_id": "img-abc123def456",
      "build_id": "bld-abc123def456"
    },
    "message": "The image is rebuilding. The application restarts when the build succeeds."
  }
}

Error Responses

string

The error code indicating the reason for failure. Possible values:

AUTH_TOKEN_MISSING, API_KEY_INVALID, SESSION_REVOKED: The Authorization header is missing, the API key is invalid, or the dashboard session was revoked (401).
API_KEY_IP_DENIED: The API key is used from an IP outside its allowlist (403).
ACCESS_DENIED: The user does not have access to the application.
API_KEY_SCOPE_DENIED: The application runs a custom Docker image and the API key does not have the images:write scope. details.required is images:write (403).
APP_NOT_FOUND: The specified application does not exist.
NO_FILE_UPLOADED: No file was provided in the request (400).
INVALID_ZIP_STRUCTURE: The zip could not be read (400).
INVALID_PATH: The path query parameter is malformed or tries to leave the application’s root, for example with .. (400).
FORBIDDEN_PATH: The destination is a folder reserved by the platform (403).
PATH_IS_FILE: The destination exists and is a file, not a folder (409).
VALIDATION_ERROR: The message is longer than 500 characters. details.path is message (400).
OPERATION_IN_PROGRESS: Another code upload for the same application is still running. Try again in a few seconds (409).
TEMPLATE_DETACH_CONFIRMATION_REQUIRED: The change would detach the application from its template and confirm_detach was not sent (409). Nothing was changed.
INTERNAL_SERVER_ERROR: An unexpected server error occurred.

{
  "code": "AUTH_TOKEN_MISSING"
}

{
  "code": "ACCESS_DENIED"
}

{
  "code": "APP_NOT_FOUND"
}

{
  "code": "NO_FILE_UPLOADED"
}

Last modified on October 28, 2026

Upload Files to Application

curl --request POST \
  --url https://api.vertracloud.app/v1/apps/{id}/files/upload \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({})
};

fetch('https://api.vertracloud.app/v1/apps/{id}/files/upload', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.vertracloud.app/v1/apps/{id}/files/upload"

payload = {}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vertracloud.app/v1/apps/{id}/files/upload"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "response": {}
}

{
  "response": {
    "image_build": {
      "image_id": "img-abc123def456",
      "build_id": "bld-abc123def456"
    },
    "message": "The image is rebuilding. The application restarts when the build succeeds."
  }
}

Overview

Endpoints

Upload Files to Application

Response

Error Responses

​Response

​Error Responses

Response

Error Responses