File V2 API

The File V2 API is an updated version of the api used to manage files in the system.

LIST

Required role: Read
Required privilege: Files.READ

Lists files.

API Endpoint: [GET]: /files

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Query Parameters

  • continuationToken: Token received from previous list request is response was truncated (used for pagination) optional
  • listAll: Set to true if you want to list all non-public files (use public: true without prefix to list all public files), should not be included otherwise. optional
  • maxKeys: The maximum number of files to get. Default is 1000. optional
  • prefix: A name prefix that all files in the response must have. optional
  • public: Set to true if you want to list public files, should not be included otherwise. optional
  • root: Set to true if you want to list files on root, should not be included otherwise. optional
  • thingName: Name of the thing that you want to list files for. optional
  • thingType: Id of the thing type that you want to list files for. optional

One of listAll, public, root, thingName or thingType is required. Only one can be included at once. continuationToken contains URI reserved characters. Make sure to encode the string before sending it. For example using:

encodeURIComponent(nextContinuationToken)

Response

  • continuationToken: The token that was used determine where to start listing files. optional
  • nextContinuationToken: Token used to get the next list of files. Include if response is truncated. optional
  • encodingType: The encoding type used to encode file names in the response. (url)
  • isTruncated: false if all files that matched the search criteria is included in the result, true otherwise.
  • keyCount: The number of files that was returned.
  • maxKeys: The maximum number of files that could be returned.
  • prefix: The prefix that was used to get the files. optional
  • files[]: A list of files matching the search criteria.
    • Key: The name of the file.
    • LastModified: The time when the files was last modified.
    • ETag: The ETag of the file that can be used for caching.
    • Size: The size of the file.
    • url: A signed url used to access the file.
    • folder:: Included if listAll is specified and the file belongs to a specific folder. optional
    • thingName:: The name of the thing. Included if listAll is specified and the file belongs to a specific thing. optional
    • thingType:: The id of the thing type. Included if listAll is specified and the file belongs to a specific thing type. optional

Errors

Key Params Property Description
NOT_AUTHORIZED Returned if the user is not authorized for the operation.
INVALID_ARGUMENTS Returned if a parameter does not fulfil requirements.

GENERATE_FILE_DOWNLOAD_URL

Required role: Read
Required privilege: Files.READ

Get a signed url to read a file from the storage.

[GET]: /files/download-url

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Query Parameters

  • fileName: The filename to retrieve. required
  • public: Set to true if you want to get a public file, should not be included otherwise. optional
  • root: Set to true if you want to get a file on root, should not be included otherwise. optional
  • thingName: The id of the specific thing. This is needed for getting files specific to a thing. optional
  • thingType: The id of the specific thing type. This is needed for getting files specific to a thing type. optional

One of public, root, thingName or thingType is required. Only one can be included at once.

Response

  • fileName: The path to the file.
  • url: The URL to use to get the file. Valid for 15 minutes.

A sample download with curl:

curl -X GET '<url>'

Errors

Key Params Property Description
NOT_AUTHORIZED Returned if the user is not authorized for the operation.
NOT_AUTHORIZED_DOMAIN Returned if the user is not authorized for root folder.
INVALID_ARGUMENTS Returned if a parameter does not fulfil requirements.
THING_NOT_FOUND Returned if the specified thing does not exist.
THING_TYPE_NOT_FOUND Returned if a targeted thing does not exist.

GENERATE_FILE_UPLOAD_URL

Required role: ReadWrite
Required privilege: Files.CREATE

Get a signed url to put a file to the storage.

[GET]: /files/upload-url

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Query Parameters

  • fileName: The filename to retrieve. required
  • public: Set to true if you want to upload a public file, should not be included otherwise. optional
  • root: Set to true if you want to upload a file on root, should not be included otherwise. optional
  • thingName: The id of the specific thing. This is needed for uploading files specific to a thing. optional
  • thingType: The id of the specific thing type. This is needed for uploading files specific to a thing type. optional
  • contentDisposition: The Content-Disposition header to be used in the PUT request. optional
  • contentEncoding: The Content-Encoding header to be used in the PUT request. optional
  • contentMD5: The Content-MD5 header to be used in the PUT request. optional
  • contentType: The Content-Type header to be used in the PUT request. optional

One of public, root, thingName or thingType is required. Only one can be included at once. The request that uses the signed url must have the same headers as specified in this request.

Response

  • fileName: The path to the file.
  • url: The URL to use to upload the file. Valid for 15 minutes.

A sample upload with curl:

curl --upload-file <your-document> '<url>'

Errors

Key Params Property Description
NOT_AUTHORIZED Returned if the user is not authorized for the operation.
NOT_AUTHORIZED_DOMAIN Returned if the user is not authorized for root folder.
INVALID_ARGUMENTS Returned if a parameter does not fulfil requirements.
THING_NOT_FOUND Returned if the specified thing does not exist.
THING_TYPE_NOT_FOUND Returned if a targeted thing does not exist.

REMOVE

Required role: ReadWrite
Required privilege: Files.DELETE

Remove a file from the storage.

[DELETE]: /files

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Query Parameters

  • fileName: The filename to delete. required
  • public: Set to true if you want to delete a public file, should not be included otherwise. optional
  • root: Set to true if you want to delete a file on root, should not be included otherwise. optional
  • thingName: The id of the specific thing. This is needed for deleting files specific to a thing. optional
  • thingType: The id of the specific thing type. This is needed for deleting files specific to a thing type. optional
  • allVersions: Set to true if you want to delete all versions of this file, should not be included otherwise. optional

Response

  • fileName: Path to the file that was deleted.

Errors

Key Params Property Description
NOT_AUTHORIZED Returned if the user is not authorized for the operation.
NOT_AUTHORIZED_DOMAIN Returned if the user is not authorized for root folder.
INVALID_ARGUMENTS Returned if a parameter does not fulfil requirements.
THING_NOT_FOUND Returned if the specified thing does not exist.
THING_TYPE_NOT_FOUND Returned if a targeted thing does not exist.