API Documentation
Toggle TOC panel
<content-service>/api/v1/versions/{versionId}/contents

URL structure

1 https://content-service.xy-company.com/api/v1/versions/{versionId}/contents

where {versionId} is the ID of a file object's/Secure Object's version.

Supported methods and overview

  • GET - downloads the data associated with a specific file object/Secure Object version (specified by versionId) from storage via the Cocoon Data Platform's Content Service.

Detailed description

This API endpoint downloads the data associated with a specific file object version (specified by versionId) from storage via the Cocoon Data Platform's Content Service.

This data can be downloaded in either unencrypted or encrypted form.

Notes:

  • Data is only stored (via the Content Service) in its encrypted form.
  • Whenever data is downloaded from the Content Service in unencrypted form, it is decrypted (after being retrieved from storage) through a separate Content Service process.

Supported roles and conditions

This API endpoint supports requests utilizing Cocoon Data user accounts with the following roles (as described in the Organisation Administrator's Guide) and conditions:

  • Originator - when this user owns the file object associated with the version whose ID is specified by {versionId} in the request's URL.
  • Originator, Collaborator and Ad hoc - when this user is a collaborator with the Rename permission on the file object associated with the version whose ID is specified by {versionId} in the URL. (The Rename permission restricts access to collaborators who have been applied either the Modify or Manage permission set on this file object.)

The Cocoon Data Platform's resources available to a Cocoon Data user meeting the criteria above is determined by the access token submitted in the header of requests to this endpoint.

Required headers

The appropriate access token as the Bearer token:

  • Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0NjcwMTY2NjYsInVzZXJfbmFtZSI6ImFsZXgub...

Required parameters

The following optional parameter can be sent in the URL of the request:

  • format - Specify either the value plaintext if downloading the file version's data in its decrypted form or encrypted if downloading the file version's encrypted data 'as is'; e.g. decryption will be conducted locally by the client application.
    Example:
    1 https://content-service.xy-company.com/api/v1/versions/987654321098765432/contents?format=encrypted

Optional parameters

The following optional parameter can be sent in the URL of the request:

  • encoding - Specify the value base64 to download the file version's data as Base64-encoded data. Otherwise, omit this parameter to download the file version's data as raw/binary data. In both cases, the Content-Type in the response is application/octet-stream.

    Example:

    1 https://content-service.xy-company.com/api/v1/versions/987654321098765432/contents?format=encrypted&encoding=base64

Returns

If the request succeeded, then an HTTP response status 200 OK is returned.