Skip to content

Assets API

Assets

Assets are files that you can upload to giosg system and that are publicly available. They are useful to hosts resources for your custom giosg products or your website components!

Even though asset contents are publicly available, they can only be accessed with an URL. In other words, only your organization members are able to see the list of your organization assets. When the asset is used somewhere, e.g. on your custom chat dialog or your website, anyone is (and need to be) able to download its contents and see its public attributes.

An asset resource has the following attributes.

Attribute Type Editable Description
id UUID read-only UUID string identifier
name string required Short, human-readable name.
description string optional Human-readable description
organization_id UUID read-only The ID of the owner organization
file_name string read-only The original file name of the uploaded file
url string read-only The full URL for original, uploaded file. Use this URL to link to your asset!
size integer read-only Size of the uploaded file in bytes
content_type string read-only Content type of the uploaded file, e.g. image/jpeg (or null if unknown)
kind string read-only What kind of file the asset is: "image", "css", "javascript", "font" or null (unknown)
charset string optional Character encoding for a text file, e.g. utf-8 (or null if binary or unknown). Must be a valid encoding name.
created_at datetime read-only When the asset was created
created_by_user_id UUID read-only The ID of the person who created this asset
created_by_user object read-only The person resource who created this asset
updated_at datetime read-only When the asset name or description was last time updated
updated_by_user_id UUID read-only The ID of the person who last time updated this asset
updated_by_user object read-only The person resource who last time updated this asset
width integer read-only The width of an image in pixels. Available for images only. It is null for other assets.
height integer read-only The height of an image in pixels. Available for images only. It is null for other assets.

Upload a new asset

Upload a file creating a new asset for a organization.

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

Warning

IMPORTANT! In contrast to the all other API endpoints, this only accepts multipart/form-data requests, because you need to upload a file with the request. The request payload takes the following attributes.

Attribute Type Editable Description
upload file required The asset file to be uploaded. File name is required. This field is optional when updating existing asset.
name string optional Name for the newly created asset. If omitted, defaults to the file name. Otherwise, it must be a non-empty string value.
charset string optional Character encoding for a text file, e.g. utf-8. Must be a valid encoding name. Defaults to null, meaning that the encoding is undefined. It is highly recommended to define a correct encoding for the uploaded text files if they are containing special characters, otherwise browsers might not read them correctly.
description string optional Description for this asset.

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 asset 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

List assets

Get a paginated collection of all the assets of your organization:

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

The endpoint accepts the following GET parameters.

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at, updated_at, name, kind or content_type in ascending order (- for descending).
kind string (none) If given, returns Assets with the given kind.
content_type string (none) If given, returns Assets with the given content_type.
description string (none) If given, returns Assets with the given description. Note: this is case sensitive.

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 asset

GET /api/v5/orgs/<organization_id>/assets/<asset_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

Update an asset

You may update the name and/or description attributes of an asset. Alternatively you may also upload new file by providing upload in payload. In this case you may also change the charset attribute. Note that charset can only be changed when uploading content for the asset.

PUT /api/v5/orgs/<organization_id>/assets/<asset_id>

PATCH /api/v5/orgs/<organization_id>/assets/<asset_id>

This endpoint returns:

  • 200 if the request was successful
  • 400 if required attribute is missing from the request
  • 401 if you are not authenticated
  • 403 if you do not have active subscription

Delete an asset

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

DELETE /api/v5/orgs/<organization_id>/assets/<asset_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 asset storage space usage:

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

This returns an object with the following attributes:

Attribute Type Description
free_space integer Total free space for new assets, in bytes
usage integer Sum of all your organization asset sizes, in bytes
limit integer The maximun allowed sum of your organization asset 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