Skip to content

Uploads API

Uploads

Uploads are files that you can upload to giosg system and they are available to be used as message attachments.

When used as chat message attachments, uploaded content is only available to users which have access to conversation where they are used. Organization users are able to see list of uploaded files but can not see the actual file unless they are participating chat conversation where the uploaded content is used.

Uploads API provides link to upload file content to Giosg CDN or organizations own CDN but does not directly store file. This means that to upload file, client needs to first do POST request to Uploads API to get signed link for uploading a file. This link can then be used to upload the actual file. Returned link is only valid for given file that it was requested for. Doing upload in two parts also allows clients to implement chat message attachment so that message with attachment get's sent before the actual upload has completed. This allows the receiving client to get message faster and show place holder image. Client can then wait until the actual file is available before showing it to user.

An Upload resource has the following attributes.

Attribute Type Editable Description
id UUID read-only UUID string identifier
original_file_name string required The original file name of the uploaded file
file_size integer required Size of the uploaded file in bytes
content_type string required Content type of the uploaded file, e.g. image/jpeg.
file_hash string required Base64 encoded md5 hash from content of the uploaded file.
upload_url object read-only Object containing url where to send the upload request and also all headers that need to be appended to form data of the POST. See upload_url object below for details.
download_url string read-only Url to download the uploaded file.
organization_id UUID read-only The ID of the owner organization
created_at datetime read-only When the upload was created
updated_at datetime read-only When the upload was modified last time
created_by_user_id UUID read-only The ID of the user who created this upload
created_by_user object read-only Details of the user who created this Upload.

upload_url object fields

Attribute Type Editable Description
url string read-only Url where to make the multipart/form-data POST to.
fields object read-only Object with keys which are required to be appended to POST request for it to succeed.

Upload a new file

Upload a file by requesting link for upload and then using that link to upload the actual file content.

POST /api/v5/orgs/<organization_id>/uploads

Attribute Type Editable Description
original_file_name string required The original file name of the uploaded file
file_size integer required Size of the uploaded file in bytes
content_type string required Content type of the uploaded file, e.g. image/jpeg.
file_hash string required Base64 encoded md5 hash from content of the uploaded file.

This endpoint returns:

  • 201 if the request was successful
  • 400 if required attribute is missing from the request
  • 400 if the upload would exceed your organization's free upload storage space
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// Calculate hash of file to be uploaded
const hash = new Md5();
const buffer = await new Response(fileBlop).arrayBuffer();
hash.appendByteArray(new Uint8Array(buffer));
const hashString = hash.end();
const hashBase64 = Buffer.from(hashString as string, "hex").toString("base64");

// Request upload link  for given file.
const uploadPayload = {
  content_type: fileBlop.type,
  file_size: fileBlop.size,
  original_file_name: original_file_name,
  file_hash: hashBase64,
};
const url = "https://service.giosg.com/api/v5/orgs/837f0981-02a9-49bb-9618-f926045e4641/uploads";
const uploadLinkResponse = await makeRequest("POST", url, uploadPayload);

// Build form data for upload and make the request
const formData = new FormData();
for (const [key, value] of Object.entries(uploadLinkResponse.upload_url.fields)) {
  formData.append(key, value);
}
formData.append("file", fileBlop);
makeUploadRequest("POST", formData);

List uploads

Get a paginated collection of all the uploaded files of your organization:

GET /api/v5/orgs/<organization_id>/uploads

The endpoint accepts the following GET parameters.

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at, updated_at, original_file_name or content_type in ascending order (- for descending).
content_type string (none) If given, returns Uploads with the given content_type.

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization

Retrieve a single upload

GET /api/v5/orgs/<organization_id>/uploads/<upload_id>

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization

Delete an upload

You may delete your uploads. Their size is freed for new file uploads.

DELETE /api/v5/orgs/<organization_id>/assets/<upload_id>

NOTE: Any previous URL (the url attribute) for the asset will stop working and the files won't be available for download any more. However, this might take a while to take effect.

This endpoint returns:

  • 201 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization

Retrieve organization's storage information

You may check your organization's current upload storage space usage:

GET /api/v5/orgs/<organization_id>/uploads/quota

This returns an object with the following attributes:

Attribute Type Description
free_space integer Total free space for new files, in bytes
usage integer Sum of all your organization uploaded file sizes, in bytes
limit integer The maximun allowed sum of your organization uploaded file sizes, in bytes

This endpoint returns:

  • 200 if the request was successful
  • 401 if you are not authenticated
  • 403 if you do not have active subscription
  • 403 if you do not have access to the organization

NOTE: If you run out of storage quota, please contact our support either on our chat or by emailing to support@giosg.com.