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,
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
The size 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,
},
});