Create or update an application file

PUT

apps

{app_id}

files

Create or update an application file

curl --request PUT \
  --url https://api.squarecloud.app/v2/apps/{app_id}/files \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "path": "<string>",
  "content": [
    {}
  ],
  "encoding": "<string>"
}
'

import requests

url = "https://api.squarecloud.app/v2/apps/{app_id}/files"

payload = {
    "path": "<string>",
    "content": [{}],
    "encoding": "<string>"
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({path: '<string>', content: [{}], encoding: '<string>'})
};

fetch('https://api.squarecloud.app/v2/apps/{app_id}/files', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.squarecloud.app/v2/apps/{app_id}/files",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'path' => '<string>',
    'content' => [
        [
                
        ]
    ],
    'encoding' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.squarecloud.app/v2/apps/{app_id}/files"

	payload := strings.NewReader("{\n  \"path\": \"<string>\",\n  \"content\": [\n    {}\n  ],\n  \"encoding\": \"<string>\"\n}")

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

	req.Header.Add("Authorization", "<authorization>")
	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))

}

HttpResponse<String> response = Unirest.put("https://api.squarecloud.app/v2/apps/{app_id}/files")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"path\": \"<string>\",\n  \"content\": [\n    {}\n  ],\n  \"encoding\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.squarecloud.app/v2/apps/{app_id}/files")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"path\": \"<string>\",\n  \"content\": [\n    {}\n  ],\n  \"encoding\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
    "status": "success"
}

string

required

The API key for your account. You can find this in your account settings.

Requires an API key with the files:write scope. Create/Modify File writes content to path inside a running application, creating the file if it does not exist or overwriting it if it does. For binary files, send content base64-encoded together with encoding: "base64", the recommended format. content also accepts a UTF-8 string for text files, a plain array of byte values ([104, 105]) or a { type: "Buffer", data: number[] } object. An empty content ("" or []) writes an empty file. Each write takes up to 10 MB, measured on the decoded bytes. Writes are rate limited to 10 requests every 5 seconds per user. Use it for small, targeted edits, such as tweaking a config value or dropping in a generated file, without re-uploading the whole application; for bulk changes or a .zip, use Commit Application instead. Writing to squarecloud.app or squarecloud.config is treated specially: the platform parses it as the application’s config (display name, description, memory, autorestart, subdomain) and validates each field, an invalid value returns a specific error code (for example INVALID_MEMORY or INVALID_SUBDOMAIN) instead of writing the file. These config rewrites are rate limited to 1 request every 15 seconds per user. On workspace-shared applications the caller needs the maintain or admin role, and members without the restricted-files permission are blocked from writing to excluded paths like .env. Like other file manager routes, this does not restart the application, call Restart Application to apply changes that need a fresh process.

Parameters

string

required

The ID of the application. You can find this in the URL of your application’s dashboard.

string

required

The path where the file should be created, up to 256 characters. Example: /test.txt

string | number[]

required

The content of the file to be created: base64 when encoding is base64, otherwise a UTF-8 string or an array of bytes.

string

Set to base64 when content is the file base64-encoded. Recommended for binary files.

Response

string

Indicates whether the call was successful: success if it was, error if not.

{
    "status": "success"
}

Common errors

Code	HTTP	Meaning
`INVALID_PATH`	400	The `path` field failed validation (traversal, invalid characters, or longer than 256 characters).
`INVALID_CONTENT`	400	`content` is missing, not one of the accepted shapes, or not valid base64 when `encoding` is `base64`.
`INVALID_DISPLAY_NAME` / `INVALID_DESCRIPTION` / `INVALID_MEMORY` / `INVALID_AUTORESTART` / `INVALID_SUBDOMAIN`	400	A field parsed from a `squarecloud.app`/`squarecloud.config` write failed validation.
`CANNOT_SET_SUBDOMAIN`	400	The parsed config tried to set a subdomain the plan or account cannot use.
`BLOCKED_PATH`	403	The caller lacks the workspace permission to write to a restricted file.
`FILE_TOO_LARGE`	413	The decoded `content` is larger than 10 MB; use Commit Application for bigger files.
`KEEP_CALM`	429	More than 10 writes in 5 seconds; wait a few seconds and retry.
`SAVE_FAILED`	500	The parsed config update could not be persisted.

CLI: squarecloud app file write
SDKs: api.apps.files.write() (JavaScript), client.apps.files.write() (Python), c.Apps.Files.Write() (Go)

Create or update an application file

curl --request PUT \
  --url https://api.squarecloud.app/v2/apps/{app_id}/files \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "path": "<string>",
  "content": [
    {}
  ],
  "encoding": "<string>"
}
'

import requests

url = "https://api.squarecloud.app/v2/apps/{app_id}/files"

payload = {
    "path": "<string>",
    "content": [{}],
    "encoding": "<string>"
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({path: '<string>', content: [{}], encoding: '<string>'})
};

fetch('https://api.squarecloud.app/v2/apps/{app_id}/files', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.squarecloud.app/v2/apps/{app_id}/files",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'path' => '<string>',
    'content' => [
        [
                
        ]
    ],
    'encoding' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.squarecloud.app/v2/apps/{app_id}/files"

	payload := strings.NewReader("{\n  \"path\": \"<string>\",\n  \"content\": [\n    {}\n  ],\n  \"encoding\": \"<string>\"\n}")

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

	req.Header.Add("Authorization", "<authorization>")
	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))

}

HttpResponse<String> response = Unirest.put("https://api.squarecloud.app/v2/apps/{app_id}/files")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"path\": \"<string>\",\n  \"content\": [\n    {}\n  ],\n  \"encoding\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.squarecloud.app/v2/apps/{app_id}/files")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"path\": \"<string>\",\n  \"content\": [\n    {}\n  ],\n  \"encoding\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
    "status": "success"
}

Get started

Account

Applications

Databases

Workspaces

AI

Create or update an application file

Parameters

Response

Common errors

​Parameters

​Response

​Common errors

​Related

Parameters

Response

Common errors

Related