> ## Documentation Index > Fetch the complete documentation index at: https://docs.cocoondata.com/llms.txt > Use this file to discover all available pages before exploring further. # /api/v1/objects/{objectId}/contents ## URL structure ```text theme={null} https://content-service.xy-company.com/api/v1/objects/{objectId}/contents ``` where `{objectId}` is the ID of a Secure Object. ## Supported methods and overview * `POST` - used to upload a [Secure Object](/3.2/api/creating-files-and-folders.md#secure-object)'s data to storage via the Covata Platform's Content Service. * `GET` - used to download a Secure Object's data from storage via the Content Service. * `DELETE` - used to delete a Secure Object's data in storage (managed by the Content Service). > [!NOTE] > > The `DELETE` method takes no parameters. ## Detailed description This API endpoint serves a number of purposes, all of which are managed by the Covata Platform's Content Service: * Uploads the data associated with a Secure Object (either in its unencrypted or encrypted form) to storage. * Downloads the data associated with a Secure Object (either in its unencrypted or encrypted form) from storage. \ **Note:** If downloading the Secure Object's data in its encrypted form, the key required to decrypt this data can be obtained by calling the [\/api/v1/objects/\{objectId}/keys](/3.2/api/access-service-api-v1-objects-objectid-keys.md) API endpoint. * Deletes the encrypted data (associated with a Secure Object) in storage. The maximum amount of data that can be uploaded in any one request is defined on the Covata Platform. The default value of this maximum amount (known as the *chunk size*) is 10 MiB. Therefore, if the total amount of data you are uploading is greater than the permitted chunk size, then the data must be uploaded as a series of chunks, each as an individual upload request to this API endpoint. > [!NOTE] > > * A *MiB* is a [mebibyte](http://physics.nist.gov/cuu/Units/binary.html), where one MiB = 1 x 1024 x 1024 bytes = 1048576 bytes. > * Data is only stored (via the Content Service) in its encrypted form. > * Whenever data is uploaded or downloaded to the Content Service in unencrypted form, it is respectively encrypted (before being sent to storage) or decrypted (after being retrieved from storage) through a separate process of the Content Service. > * If you intend to [delete a Secure Object](/3.2/api/access-service-api-v1-objects-objectid.md) and change its state to *Deleted*, then call this API endpoint on this Secure Object *first*. This avoids problems where a Covata user's actual quota may differ from the quota reported by the Covata Platform (until this data is automatically deleted by the Content Service). See [\/api/v1/objects/\{objectId}](/3.2/api/access-service-api-v1-objects-objectid.md) for more information. ## Supported roles and conditions This API endpoint supports the following Covata user roles (as described in the [Covata Platform Administrator's Guide](/3.2/admin.md)), conditions and [permissions](/3.2/api/access-service-api-v1-permissions-sets.md) (where applicable): * [Originator](/3.2/admin-org/administering-users-within-an-organisation.md#originator-role) - a Covata user with this role can call the `POST` method for a Secure Object they have [initialized/created](/3.2/api/access-service-api-v1-organisations-orggroupid-objects.md), as well as the `GET` and `DELETE` methods on a Secure Object they own. * **Originator**, [Collaborator](/3.2/admin-org/administering-users-within-an-organisation.md#collaborator-role) and [Ad hoc](/3.2/admin-org/administering-users-within-an-organisation.md#adhoc-role) - a Covata user with any of these roles can call: * the `POST` method for a Secure Object they have initialized/created within a [collection](/3.2/api/creating-files-and-folders.md#collection) that this user has the **Upload File** *permission* on, * the `GET` method for a Secure Object they are a collaborator on (with the **Download** *permission*) and * the `DELETE` method for a Secure Object they are a collaborator on (with the **Remove (File)** *permission*). The Covata Platform's resources available to one of these Covata users (above) is determined by the access token passed in the [header](/3.2/api/content-service-api-v1-objects-objectid-contents.md#content-service-api-v1-objects-objectid-contents-required-headers) of requests to this endpoint. ## Required headers The appropriate access token as the `Bearer` token: * `Authorization: Bearer a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6` The following header is also required in a POST request to allow multi-part (including binary) form data elements to be uploaded through the request: * `Content-Type: multipart/form-data` > [!NOTE] > > It is also worth appending to this header a `boundary` parameter, whose string value is used to demark each multi-part form data element of the request (i.e. this string is not used for any other purpose throughout the entire request). \\ > > For example, to use the following string to demark each multi-part form data element: \\ > > `-----------------------------12345678901234567890123456` \\ > > assign this string value to the `boundary` parameter, which in turn is appended to the `Content-Type: multipart/form-data` header, such that this header will be: \\ > > `Content-Type: multipart/form-data; boundary=-----------------------------12345678901234567890123456` ## Required parameters on POST The following required parameter must be sent in the URL of the POST request: * **format** - Specify either the value `plaintext` (if uploading unencrypted data to the Covata Platform's Content Service) or `encrypted` (if the data was pre-encrypted before uploading; e.g. encryption was conducted locally by the client application). \ **Notes:** * If you are uploading data in more than one *chunk upload request* (see [Required parameters for multi-chunk uploads](/3.2/api/content-service-api-v1-objects-objectid-contents.md#content-service-api-v1-objects-objectid-contents-required-parameters-for-multi-chunk-uploads) below for details) then this parameter must be specified in each request. * If you are pre-encrypting your data before uploading it to storage via the Content Service, then ensure that this data is encrypted using: * The AES algorithm (in CBC mode) with [PKCS #7 padding](http://tools.ietf.org/html/rfc2315) (see [\/api/v1/keys](/3.2/api/access-service-api-v1-keys.md) for more information), as well as * The [cryptographic key and initialization vector](/3.2/api/access-service-api-v1-keys.md#access-service-api-v1-keys-returns) (returned by calling the [\/api/v1/keys](/3.2/api/access-service-api-v1-keys.md) API endpoint) for the key associated with this [Secure Object](/3.2/api/creating-files-and-folders.md#secure-object). If you do not follow these encryption guidelines, then either your attempt to upload your encrypted data may fail or if successful, any attempt to [download](/3.2/api/content-service-api-v1-objects-objectid-contents.md#content-service-api-v1-objects-objectid-contents-required-parameters-on-GET) the Secure Object's data in its decrypted form will result in the retrieval of garbled data. **Example:** ```text theme={null} https://content-service.xy-company.com/api/v1/objects/987654321098765432/contents?format=plaintext ``` Additionally, the following required parameters must be sent in the body of the POST request, each as individual multi-part form data elements: * **data** - The actual unencrypted or encrypted data to be uploaded to the Covata Platform's Content Service. \ **Notes:** * If the total amount of data you are uploading is greater than the *chunk size* permitted by the Covata Platform (e.g. 10 MiB), then you must upload this data as part of a multi-chunk upload and more parameters are required with each *chunk upload request*; see [Required parameters for multi-chunk uploads](/3.2/api/content-service-api-v1-objects-objectid-contents.md#content-service-api-v1-objects-objectid-contents-required-parameters-for-multi-chunk-uploads) (below) for details. Your client application will be responsible for extracting the appropriately-sized data chunks sequentially (for submission with each chunk upload request) from the total amount of data to be uploaded. * The default `Content-Type` for this parameter is `application/octet-stream` \ **Note:** Use this `Content-Type` for any multi-chunk upload. * **totalFileSizeBytes** - The size (in bytes) of the total amount of unencrypted or encrypted data to be uploaded. \ **Note:** If you are uploading data in more than one *chunk upload request* (see [Required parameters for multi-chunk uploads](/3.2/api/content-service-api-v1-objects-objectid-contents.md#content-service-api-v1-objects-objectid-contents-required-parameters-for-multi-chunk-uploads) below for details), then this parameter must be specified in each chunk upload request. **Example (uploading data less than or equal to the *chunk size* permitted by the Covata Platform in a single request):** ```text theme={null} -----------------------------12345678901234567890123456 Content-Disposition: form-data; name="totalFileSizeBytes" 549732 -----------------------------12345678901234567890123456 Content-Disposition: form-data; name="data"; filename="paraglider.jpg" Content-Type: image/jpeg {YOUR ACTUAL UNENCRYPTED OR ENCRYPTED DATA HERE} -----------------------------12345678901234567890123456 ``` ## Required parameters for multi-chunk uploads If the total amount of data being uploaded is greater than the *chunk size* permitted by the Covata Platform, then divide this amount of data by this chunk size. The data must then be uploaded chunk-by-chunk in a series of POST requests to this API endpoint (each of which is referred to as a *chunk upload request*), until all data has been uploaded. In addition to the parameters [above](/3.2/api/content-service-api-v1-objects-objectid-contents.md#content-service-api-v1-objects-objectid-contents-required-parameters-on-POST), the following parameters must also be sent in the body of each chunk upload request. Each of these parameters must be sent as individual multi-part form data elements: * **bucket** ( *Only used after the first 'chunk upload request'* ) - Specify the value of the **bucket** member returned in response to the previous chunk upload request. As such, this parameter is not specified in the first chunk upload request. * **chunkSize** - The size (in bytes) of the unencrypted or encrypted data being uploaded to the Covata Platform's Content Service (for storage) in this *chunk upload request*. \ Assuming the default Covata Platform upload limit of 10 MiB, specify a value of `10485760` (bytes) for the first chunk upload request. Then continue specifying this value in subsequent upload requests (each containing a subsequent 10 MiB chunk of the data being uploaded) until the following upload request of 10 MiB (which is the final one) exceeds the remainder of the total amount of data being uploaded. For this final upload request, specify the remaining amount of the total data instead. \ For example, if you are uploading 48 MiB file, you would send four chunk upload requests of 10 MiB (each of whose **chunkSize** value would be `10485760`) followed by a final chunk upload request of 8 MiB (whose **chunkSize** value would be `8388608`). * **etags\[X]** ( *Only used in the final 'chunk upload request'* ) - Specify the value of each **etags** member returned in all previous *chunk upload requests*. A given **etags** parameter in the final chunk upload request has a value of **X** and an associated alphanumeric string value, which corresponds respectively to the **X** sub-member (and its associated value) of the **etags** member returned in the [response](/3.2/api/content-service-api-v1-objects-objectid-contents.md#response-from-an-intermediate-POST-request) from a respective chunk upload request. \ Following on from the 48 MiB file example (above), the final chunk upload request would contain four **etags** parameters. * **partByteOffset** - The number of bytes from the beginning of the total amount of data, where the start of the actual data being uploaded (in this *chunk upload request*) commences. \ For example, following on from the 48 MiB file example (above), the value of this **partByteOffset** parameter's value would be `0` in the first chunk upload request. In the second chunk upload request, this parameter's value would be `10485760`. In the third request, this parameter's value would be `20971520` (i.e. `10485760` + `10485760`) and so on. * **partIndex** - The index number for the chunk of data being submitted in this *chunk upload request*, starting from `0`. For example, for the first chunk upload request, **partIndex** would be `0`; for the second chunk upload request, **partIndex** would be `1`; for the third, **partIndex** would be `2` and so on. * **totalParts** - The total number of *chunk upload requests* required to upload the total amount of unencrypted or encrypted data. \ Following on from the 48 MiB file example (above), **totalParts** would be `5`. * **uploadId** ( *Only used after the first 'chunk upload request'* ) - Specify the value of the **uploadId** member returned in response to the previous chunk upload request. As such, this parameter is not specified in the first chunk upload request. **Example (uploading data greater than the *chunk size* permitted by the Covata Platform - first *chunk upload request*):** ```text theme={null} -----------------------------12345678901234567890123456 Content-Disposition: form-data; name="partIndex" 0 -----------------------------12345678901234567890123456 Content-Disposition: form-data; name="partByteOffset" 0 -----------------------------12345678901234567890123456 Content-Disposition: form-data; name="chunkSize" 10485760 -----------------------------12345678901234567890123456 Content-Disposition: form-data; name="totalParts" 3 -----------------------------12345678901234567890123456 Content-Disposition: form-data; name="totalFileSizeBytes" 29360128 -----------------------------12345678901234567890123456 Content-Disposition: form-data; name="data"; filename="blob" Content-Type: application/octet-stream {FIRST CHUNK OF YOUR ACTUAL UNENCRYPTED OR ENCRYPTED DATA HERE} -----------------------------12345678901234567890123456 ``` **Example (second *chunk upload request* - based on the example [response](/3.2/api/content-service-api-v1-objects-objectid-contents.md#response-from-an-intermediate-POST-request) below from the [first](/3.2/api/content-service-api-v1-objects-objectid-contents.md#first-chunk-upload-request) request above):** ```text theme={null} -----------------------------12345678901234567890123456 Content-Disposition: form-data; name="uploadId" wJPRDiq.jZPqt2_NcDA_vegX5L.O78LJ2vrM7WnT6dRNu21knO_znnvEp4nBrQ-- -----------------------------12345678901234567890123456 Content-Disposition: form-data; name="bucket" 987654321019181716 -----------------------------12345678901234567890123456 Content-Disposition: form-data; name="partIndex" 1 -----------------------------12345678901234567890123456 Content-Disposition: form-data; name="partByteOffset" 10485760 -----------------------------12345678901234567890123456 Content-Disposition: form-data; name="chunkSize" 10485760 -----------------------------12345678901234567890123456 Content-Disposition: form-data; name="totalParts" 3 -----------------------------12345678901234567890123456 Content-Disposition: form-data; name="totalFileSizeBytes" 29360128 -----------------------------12345678901234567890123456 Content-Disposition: form-data; name="data"; filename="blob" Content-Type: application/octet-stream {SECOND CHUNK OF YOUR ACTUAL DATA HERE} -----------------------------12345678901234567890123456 ``` **Example (final *chunk upload request* - based on the example [response](/3.2/api/content-service-api-v1-objects-objectid-contents.md#response-from-an-intermediate-POST-request) below from the [second](/3.2/api/content-service-api-v1-objects-objectid-contents.md#second-chunk-upload-request) request above):** ```text theme={null} -----------------------------12345678901234567890123456 Content-Disposition: form-data; name="etags[1]" ff57684136e0777df45a8a8b1c7d6f28 -----------------------------12345678901234567890123456 Content-Disposition: form-data; name="etags[2]" a6aed0899c6063d671534f01d1170841 -----------------------------12345678901234567890123456 Content-Disposition: form-data; name="uploadId" wJPRDiq.jZPqt2_NcDA_vegX5L.O78LJ2vrM7WnT6dRNu21knO_znnvEp4nBrQ-- -----------------------------12345678901234567890123456 Content-Disposition: form-data; name="bucket" 987654321019181716 -----------------------------12345678901234567890123456 Content-Disposition: form-data; name="partIndex" 2 -----------------------------12345678901234567890123456 Content-Disposition: form-data; name="partByteOffset" 20971520 -----------------------------12345678901234567890123456 Content-Disposition: form-data; name="chunkSize" 8388608 -----------------------------12345678901234567890123456 Content-Disposition: form-data; name="totalParts" 3 -----------------------------12345678901234567890123456 Content-Disposition: form-data; name="totalFileSizeBytes" 29360128 -----------------------------12345678901234567890123456 Content-Disposition: form-data; name="data"; filename="blob" Content-Type: application/octet-stream {FINAL CHUNK OF YOUR ACTUAL DATA HERE} -----------------------------12345678901234567890123456 ``` ## Required parameters on GET The following required parameter must be sent in the URL of the GET request: * **format** - Specify for this parameter's value either `plaintext` (if downloading the [Secure Object](/3.2/api/creating-files-and-folders.md#secure-object)'s data in its decrypted form) or `encrypted` (if downloading the the Secure Object's encrypted data 'as is'; for example, to decrypt locally through the client application). **Example:** ```text theme={null} https://content-service.xy-company.com/api/v1/objects/987654321098765432/contents?format=plaintext ``` ## Returns from a POST request A JSON-formatted response containing the following members: * **objectId** - The ID value of the Secure Object. This value should match the `{objectId}` value specified specified in the [URL of this request](/3.2/api/content-service-api-v1-objects-objectid-contents.md#content-service-api-v1-objects-objectid-contents-url-structure). * **success** - A boolean value that indicates `true` if the request succeeded or `false` if the request failed. * **uploadId** - A hash string value returned after the first *chunk upload request* of a multi-chunk upload. This value: * Is a unique identifier for the total amount of data (associated with the [Secure Object](/3.2/api/creating-files-and-folders.md#secure-object)) to be uploaded to storage via the Covata Platform's Content Service, * Is returned in every response to every request throughout a multi-chunk upload. This value must be included in all requests (following the initial request) of a multi-chunk upload. See [Required parameters for multi-chunk uploads](/3.2/api/content-service-api-v1-objects-objectid-contents.md#content-service-api-v1-objects-objectid-contents-required-parameters-for-multi-chunk-uploads) (above) for more information. **Note:** This value is `null` in responses from requests to upload data which is either less than or equal to the *chunk size* permitted by the Covata Platform. ### Additional members returned from a single or final POST request In a response from either: * A request to upload data which is either less than or equal to the *chunk size* permitted by the Covata Platform, or * The final request to upload data which is greater than the *chunk size* permitted by the Covata Platform (i.e. the final request of a multi-chunk upload), the following members are also returned: * **sha512** - The unique [SHA-512](http://csrc.nist.gov/publications/fips/fips180-4/fips-180-4.pdf) hash value of the encrypted data associated with the created/complete Secure Object. * **contentSize** - The amount of space (in bytes) of the Secure Object's data (as recorded by the Covata Platform's Access Service). * **uploadedAs** - Indicates `plaintext` if unencrypted data was uploaded to storage, or `encrypted` if pre-encrypted data was uploaded. \ **Note:** This value should match the value of the **format** [URL parameter](/3.2/api/content-service-api-v1-objects-objectid-contents.md#content-service-api-v1-objects-objectid-contents-required-parameters-on-POST) submitted in each POST request to this API endpoint. **Example (uploading data less than or equal to the *chunk size* permitted by the Covata Platform - response from the [single](/3.2/api/content-service-api-v1-objects-objectid-contents.md#single-request) request above):** ```json theme={null} { "objectId": "987654321098765432", "success": true, "uploadId": null, "sha512": "mDxrkb0Nj5m44ZPYxgIJOvHckXHr577f8Ww4VGxssQ60yv5pyhtrrlepL2ZNCNytLRdwcY4CrwRQmiEG\/0y5Mw==", "contentSize": 549732, "uploadedAs": "plaintext" } ``` **Example (uploading data greater than the *chunk size* permitted by the Covata Platform - response from the [final](/3.2/api/content-service-api-v1-objects-objectid-contents.md#final-chunk-upload-request) *chunk upload request* above):** ```json theme={null} { "objectId": "987654321012345678", "success": true, "uploadId": "wJPRDiq.jZPqt2_NcDA_vegX5L.O78LJ2vrM7WnT6dRNu21knO_znnvEp4nBrQ--", "sha512": "Ii5TdQLLK7s4KjWmAWrHGVf6UFOHR8f3BHnYgzu5w+RVHdDS+hhGT0z2Hxo8xyvVUcfhGBiWi9pXuQa+LHOjag==", "contentSize": 12582912, "uploadedAs": "plaintext" } ``` ### Additional members returned from an intermediate POST request In a response from a multi-chunk upload request (except for the final response), the following members are also returned: * **bucket** - A unique identifier for the location in storage where the encrypted data of a multi-chunk upload is held. This value is returned in every response to every request throughout a multi-chunk upload and must be included in all requests (following the initial request) of a multi-chunk upload. See [Required parameters for multi-chunk uploads](/3.2/api/content-service-api-v1-objects-objectid-contents.md#content-service-api-v1-objects-objectid-contents-required-parameters-for-multi-chunk-uploads) (above) for more information. * **etags** - A member containing the sub-member **X** (a number representing the sequential index number of this request in a multi-chunk upload, starting from `1`), whose value is an alphanumeric string value. \ **Important:** Your client application needs to collate the **etags** sub-members of each multi-chunk upload request, since each one of these needs to be included in the final *chunk upload request*. See [Required parameters for multi-chunk uploads](/3.2/api/content-service-api-v1-objects-objectid-contents.md#content-service-api-v1-objects-objectid-contents-required-parameters-for-multi-chunk-uploads) (above) for more information. **Example (uploading data greater than the *chunk size* permitted by the Covata Platform - response from the [first](/3.2/api/content-service-api-v1-objects-objectid-contents.md#first-chunk-upload-request) *chunk upload request* above):** ```json theme={null} { "objectId": "987654321012345678", "bucket": "987654321019181716", "success": true, "etags": { "1": "ff57684136e0777df45a8a8b1c7d6f28" }, "uploadId": "wJPRDiq.jZPqt2_NcDA_vegX5L.O78LJ2vrM7WnT6dRNu21knO_znnvEp4nBrQ--" } ``` **Example (response from the [second](/3.2/api/content-service-api-v1-objects-objectid-contents.md#second-chunk-upload-request) *chunk upload request* above):** ```json theme={null} { "objectId": "987654321012345678", "bucket": "987654321019181716", "success": true, "etags": { "2": "a6aed0899c6063d671534f01d1170841" }, "uploadId": "wJPRDiq.jZPqt2_NcDA_vegX5L.O78LJ2vrM7WnT6dRNu21knO_znnvEp4nBrQ--" } ``` ## Returns from a GET or DELETE request If you submitted either a: * GET request to download a [Secure Object](/3.2/api/creating-files-and-folders.md#secure-object)'s data, or a * DELETE request to delete the encrypted data (in storage via the Covata Platform's Content Service) associated with a Secure Object and the request succeeded, then an HTTP response of status `200 OK` is returned. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.