Files

Samply offers you the ability to upload your files to a project through the API.

First, request an upload URL from an endpoint. Then use that URL to upload a file directly to your project.

You can also skip the documentation and skip directly to example code.

Request an upload URL

First, you'll request an upload URL from a project-specific /files endpoint. The file you'll upload will follow the File interface as defined here.

Request type POST

Endpoint /projects/:projectid/files

Body

{
  name: string,
  mimeType: string,
  size: number | string,
  parentid: string
}

---

name string

The name parameter on the File.

---

mimeType string

The mime type as defined by the type parameter on the File.

---

size number | string

The size in bytes as defined by the size parameter on the File.

---

parentid string optional

An optional id to specify a stack or folder within the project that this file will be uploaded to.

Upload URL response

The request will return an object with the following structure.

{
  boxid: string,
  contentType: string,
  metadata: {
    boxpath: string,
    destination: string,
    projectid: string,
  },
  stackid: string,
  url: string
}

---

boxid string readonly

The id to the asset you will be uploading.

---

contentType string readonly

File content type as returned by the server.

---

metadata object readonly

Upload metadata.

Child attributes

---

boxpath string readonly

Path to box document in the database.

---

destination string readonly

Internal file destination indicator.

---

projectid string readonly

Project id file will upload to.

---

stackid string readonly

Stack id that the file will be uploaded to.

---

url string readonly

Upload URL.

Upload your file

Now that we have our upload URL, our File, and our metadata, it's time to upload the file.

Request type PUT

Endpoint is the url field returned from the previous request.

Body is the File.

The headers will be populated with fields from the previous response.

A full example is provide below.

Example upload

Below is example code for the upload API flow. We receive a file from an HTMLInputElement, request an upload URL for that file, then upload the file with a PUT request.

const projectid = "testprojectid"

// File uploaded from HTMLInputElement
const fileInput = document.getElementById("fileInput") as HTMLInputElement;
const files = fileInput.files;
const file = files[0] as File;

// Request upload URL
const response = await fetch(`${baseUrl}/projects/${projectid}/files`, {
  method: "POST",
  body: JSON.stringify({
    name: file.name,
    mimeType: file.type,
    size: file.size,
  }),
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
});
const jsonResponse = await response.json();

// Upload file
const url = jsonResponse.url;
const uploadResponse = await fetch(url, {
  method: "PUT",
  body: file,
  headers: {
    "x-goog-meta-destination": jsonResponse.metadata.destination,
    "x-goog-meta-projectid": jsonResponse.metadata.projectid,
    "x-goog-meta-boxpath": jsonResponse.metadata.boxpath,
    "Content-Type": jsonResponse.contentType,
  },
});

Delete a file

This endpoint deletes a file by id. It returns an empty object and 200 status on successful deletion. Additionally, if the file being deleted is the only version within a stack, that stack will be deleted as well.

Request type DELETE

Endpoint /projects/:projectid/files/:fileid