Files API

A project can store files, such as uploads, images and documents. They live in object storage and are served by the platform at /_files/{path} on the project's address, so an idle project still serves them without starting. For how they are served, see Files.

GET/projects/{name}/filesEvery stored file

POST/projects/{name}/files/{path}Upload a file, replacing one at the same path

POST/projects/{name}/rename-file/{path}Move a file to a new path

DELETE/projects/{name}/files/{path}Delete a file

File paths

{path} is the rest of the URL after files/ or rename-file/, and may contain slashes: avatars/ada.png. Percent-encode each segment, not the slashes between them. A leading / is ignored and . segments are dropped. A path that is empty, longer than 512 characters, contains a line break or uses .. to step outside the project is refused with 400.

Files are served with a type chosen from the extension: common image, font, audio, video, PDF, text, CSV, JSON and ZIP types. Anything else, HTML included, is served as application/octet-stream, so an upload never runs as a page on your project's origin.

List files

GET/projects/{name}/filesEvery stored file

namestringRequired

Path parameter. The project's name.

Terminal

curl https://api.fortly.com/projects/my-app-ada/files \
  -H "Authorization: Bearer $FORTLY_TOKEN"

JavaScript

const res = await fetch("https://api.fortly.com/projects/my-app-ada/files", {
  headers: { Authorization: `Bearer ${process.env.FORTLY_TOKEN}` },
});
const { files } = await res.json();

JSON

{
  "files": [
    {
      "path": "avatars/ada.png",
      "bytes": 48213,
      "modified": 1791820800,
      "url": "https://my-app-ada.fortly.com/_files/avatars/ada.png"
    }
  ]
}

modified is Unix seconds, or null when storage does not report it. url is where visitors fetch the file.

Upload a file

POST/projects/{name}/files/{path}Upload a file, replacing one at the same path

The body is the file's bytes, sent raw, up to 64 MB. A file already at this path is replaced, and the edge cache for the project is cleared so the new one is served.

namestringRequired

Path parameter. The project's name.

pathstringRequired

Path parameter. Where to store it, such as avatars/ada.png. See File paths.

Terminal

curl -X POST https://api.fortly.com/projects/my-app-ada/files/avatars/ada.png \
  -H "Authorization: Bearer $FORTLY_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @ada.png

JavaScript

import { readFile } from "node:fs/promises";

const res = await fetch("https://api.fortly.com/projects/my-app-ada/files/avatars/ada.png", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FORTLY_TOKEN}`,
    "Content-Type": "application/octet-stream",
  },
  body: await readFile("ada.png"),
});
const { path, bytes } = await res.json();

Answers 201:

JSON

{
  "path": "avatars/ada.png",
  "bytes": 48213,
  "url": "http://my-app-ada.fortly.com/_files/avatars/ada.png"
}

path is the cleaned path the file was stored under. The url in this response is always built as http://{host}/_files/{path}. For the address visitors should use, with the project's real scheme, take url from List files or Rename a file.

Status	When
`400`	The body is empty (`that file is empty`), or the path is refused.
`413`	The file is over 64 MB.

Rename a file

POST/projects/{name}/rename-file/{path}Move a file to a new path

Moves a stored file to a new path. The file is copied to the new path first and the old one is deleted only after that, so a failure never loses it.

namestringRequired

Path parameter. The project's name.

pathstringRequired

Path parameter. The file's current path.

tostringRequired

Body. The new path, under the same rules. A file already there is replaced.

Terminal

curl -X POST https://api.fortly.com/projects/my-app-ada/rename-file/avatars/ada.png \
  -H "Authorization: Bearer $FORTLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to":"avatars/ada-lovelace.png"}'

JavaScript

const res = await fetch(
  "https://api.fortly.com/projects/my-app-ada/rename-file/avatars/ada.png",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.FORTLY_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ to: "avatars/ada-lovelace.png" }),
  },
);
const file = await res.json();

JSON

{
  "path": "avatars/ada-lovelace.png",
  "bytes": 48213,
  "url": "https://my-app-ada.fortly.com/_files/avatars/ada-lovelace.png"
}

Status	When
`400`	A path is refused, or `to` is the file's current path (`that is already its name`).
`404`	No file at `{path}` (`no such file`).

Delete a file

DELETE/projects/{name}/files/{path}Delete a file

Deletes the file and clears the edge cache for the project.

namestringRequired

Path parameter. The project's name.

pathstringRequired

Path parameter. The file's path.

Terminal

curl -X DELETE https://api.fortly.com/projects/my-app-ada/files/avatars/ada.png \
  -H "Authorization: Bearer $FORTLY_TOKEN"

JavaScript

await fetch("https://api.fortly.com/projects/my-app-ada/files/avatars/ada.png", {
  method: "DELETE",
  headers: { Authorization: `Bearer ${process.env.FORTLY_TOKEN}` },
});

Answers 204 No Content. Deleting a path that holds no file also answers 204.