> ## 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 ## URL structure ```text theme={null} https://access-service.xy-company.com/api/v1/objects ``` ## Supported methods and overview * `GET` - retrieves information about the active version of a file object/[Secure Object](/CS1.2/api/working-with-files-and-folders-fundamentals.md#secure-object) using the SHA-512 value of its encrypted data. ## Detailed description This API endpoint retrieves information about the active version of a file object using the [SHA-512](http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf) hash value of its encrypted data (i.e. matching the SHA-512 value recorded in the file object upon its completion). > [!NOTE] > > * This API endpoint is only available if the Cocoon Data user (whose [access token is submitted in the request to this endpoint](/CS1.2/api/access-service-api-v1-objects.md#access-service-api-v1-objects-supported-roles-and-conditions)) has access to this file object (as either the owner of or a collaborator on this file). > * The SHA-512 value specified in the request must match that of SHA-512 value recorded in the file object (upon the file object's completion), because for every time a given piece of data is encrypted (i.e. using AES), the SHA-512 of the encrypted data will be different. ## Supported roles and conditions This API endpoint supports requests utilising Cocoon Data user accounts with the following [roles](/CS1.2/admin-org/administering-users-within-an-organisation.md#an-organisation-users-roles) (as described in the [Organisation Administrator's Guide](/CS1.2/admin-org.md)) and conditions: * [Originator](/CS1.2/admin-org/administering-users-within-an-organisation.md#originator-role) - when this user owns the file object. * **Originator**, [Collaborator](/CS1.2/admin-org/administering-users-within-an-organisation.md#collaborator-role) and [Ad hoc](/CS1.2/admin-org/administering-users-within-an-organisation.md#adhoc-role) - when this user is a collaborator on the file object. \ **Note:** If this user also has the **View Other** [permission](/CS1.2/api/access-service-api-v1-permissions-sets.md) on the file object, additional information is returned in the response. 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](/CS1.2/api/access-service-api-v1-objects.md#access-service-api-v1-objects-required-headers) of requests to this endpoint. ## Required headers The appropriate access token as the `Bearer` token: * `Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0NjcwMTY2NjYsInVzZXJfbmFtZSI6ImFsZXgub...` ## Required parameters The following required parameter must be sent in the **URL** of the GET request: * **sha512** - The unique [SHA-512](http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf) hash value of the encrypted data associated with the file object, which the Cocoon Data user (whose account's access token was used to call this API endpoint) owns or is a collaborator on. See [Supported roles and conditions](/CS1.2/api/access-service-api-v1-objects.md#access-service-api-v1-objects-supported-roles-and-conditions) above for details. \ **Example (request):** ```text theme={null} https://access-service.xy-company.com/api/v1/objects?sha512=0X3iJ2keHhOBzrdJmUCw2QO0r7OOAwtaWDHGKU5cnkHVhdjeWtyvQAjjwAigT2dakgtM/BeZ/qvjuwAUtG9FdA== ``` ## Returns If the request succeeded, then an HTTP response status `200 OK` is returned. For successful requests only, a JSON-formatted response containing the following members is also returned: * **id** - The ID value of the file object. * **shareStartTime** - The date and time from which collaborators on this file object can begin accessing the file's content. This value is `null` if the **shareStartTime** was never specified when the file object was [initialised or created](/CS1.2/api/access-service-api-v1-organisations-orggroupid-objects.md), or [last updated](/CS1.2/api/access-service-api-v1-objects-objectid.md). * **shareEndTime** - The date and time from which collaborators' access to this file object's content ceases. This value is `null` if the **shareEndTime** was never specified when the file object was initialised or created, or last updated. * **shared** - A boolean value that indicates whether or not the file object has been shared with any collaborators. * **name** - The name of the file object, which was set when the file object was [initialised or created](/CS1.2/api/access-service-api-v1-organisations-orggroupid-objects.md), or [last updated](/CS1.2/api/access-service-api-v1-objects-objectid.md). This value is `null` if the **name** was never specified. * **sha512** - The unique [SHA-512](http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf) hash value of the encrypted data associated with this *Created*/complete file object. This value should match that of the **sha512** parameter value submitted in the request to this API endpoint. * **owner** - A member containing information about the Cocoon Data user who is the current owner of the file object. This member contains the following sub-members: * **email** - This email address of the Cocoon Data user who owns this file object. * **firstName** - The first name set by this Cocoon Data user. This is the first name that appears on the [Users](/CS1.2/admin-org/administering-users-within-an-organisation.md) page of SafeShare Organisation Administration and the [My Account](/CS1.2/user/managing-your-account.md) feature of Cocoon Data SafeShare for Web. * **lastName** - The last name set by this Cocoon Data user. Like the first name (above), this appears on the **User** page of Organisation Administration and the **My Account** feature of SafeShare for Web. * **mfaEnabled** - A boolean value that indicates whether or not two-factor authentication has either been set by this Cocoon Data user on their own account, or enforced for all members of the organisation (by an Organisation administrator). * **id** - The ID of this Cocoon Data user's account. * **accountType** - A member containing the internationalisation (I18N) property key/code \* for the account type, including the account type's value (i.e. hard-coded in the Cocoon Data Platform), as sub-members: * **i18n** - A member containing the I18N code \* for the account type as sub-members: * **code** - The I18N code for the account type's value, beginning with `server.useraccounttype.` This I18N code could include the substring `local`, `ldap` or `external`. * **arguments** - An array containing any arguments/variables that constitute the value of the I18N code above. Since none of the account types' values contain any variables, this array is always empty. * **value** - The value of **accountType** as it is hard-coded in the Cocoon Data Platform. Your client application can exploit this value (instead of **i18n** above) if I18N is not required. \* Your client application can exploit the Cocoon Data Platform's I18N features, by initially [downloading the relevant language bundles](/CS1.2/api/access-service-api-v1-i18n-bundles-localecode-download.md) (from the Cocoon Data Platform), then using the **i18n code** (and if applicable, **arguments**) values above to extract the property values derived from these language bundles for use in your client application. For more information about the Cocoon Data Platform's I18N features, see Managing internationalisation in the SafeShare Administrator's Guide. \ **Note:** For more information about account types, see the description for [Account Type](/CS1.2/admin-org/administering-users-within-an-organisation.md#account-type) in the [Organisation Administrator's Guide](/CS1.2/admin-org.md). * **hasView** - A boolean value that indicates whether or not the Cocoon Data Platform's Content Service has generated a read-only view of the file object's data in storage. \ **Notes:** * The Content Service automatically sets this value to `true` *after* it sets the value of **canGenerateView** (below) to `true` *and* the Content Service has successfully generated and stored a read-only view of the file object's data. * If your client application is managing its own file data (i.e. the data is not being uploaded to the Content Service), then your application can exploit this element's value for any purpose. * **canGenerateView** - A boolean value that indicates whether or not the Content Service is capable of generating a read-only view of the file object's data, which is based on the file name extension of the original file that was encrypted (as specified in **name**). For more information, see [File formats supported by the content viewer](/CS1.2/user/accessing-secure-content.md#file-formats-supported-by-the-content-viewer) in SafeShare for Web User's Guide. \ **Notes:** * Assuming the file name extension is one that supports a view being generated, the Content Service then automatically sets this value to `true` *after* the file object's data has been successfully [uploaded and stored](/CS1.2/api/content-service-api-v1-objects-objectid-contents.md#content-service-api-v1-objects-objectid-contents-required-post-request-parameters) *and* the size of this data is less than the maximum configured file size for generating a view (i.e. 20 MB by default). * If your client application is managing its own file object data (i.e. the data is not being uploaded to the Content Service), then your application can exploit this element's value for any purpose. * **extension** - The file name extension which appears after the final period/full-stop of the file object's **name**. * **organisation** - A member containing information about the organisation in which this file object was created. This member contains the following sub-members: * **name** - The name of the organisation. * **description** - The description of the organisation, which can be set by Organisation administrators. * **mfaEnabled** - A boolean value that indicates whether or not two-factor authentication has been enforced for all members of the organisation. * **id** - The ID of the organisation. * **permissions** - An array listing the individual [permissions](/CS1.2/api/access-service-api-v1-permissions-sets.md) that the **owner** above or one of the **collaborators** below (whose access token was used in the request to this endpoint), has inherited from the location represented by **parentId**. \ **Note:** A bug in this version of the Cocoon Data Platform results in this property always returning an empty array in any requests to this endpoint. * **mimeType** - The MIME type of the data associated with the file object, which was set when the file object was [initialised or created](/CS1.2/api/access-service-api-v1-organisations-orggroupid-objects.md), or [last updated](/CS1.2/api/access-service-api-v1-objects-objectid.md). This value is `null` if the **mimeType** was never specified on this file object. * **contentSize** - The amount of space (in bytes) of the file object's data (as recorded by the Cocoon Data Platform's Access Service). * **parentId** - The ID of the [folder/collection](/CS1.2/api/folder-handling-endpoints.md) that contains the file object. A value of `0` indicates that this file object is located at the logical root location. * **originator** - A member containing information about the Cocoon Data user whose account was used to create this file object. This member contains the equivalent **email** and **id** sub-members only of either the **owner** member (above) or a **collaborators** array element (below). If these sub-members originally match those of the file's initial **owner** member and then the file's ownership changes to that of another Cocoon Data user, the **owner** member's **email** and **id** values will change while the equivalent sub-member values of this **originator** member will remain unchanged. * **state** - The I18N code for the current state of the file object. This I18N code could include the substring `incomplete` for an initialised file object, `created` for a completed file or `deleted` for a deleted file. * **modifiedAt** - The date and time when the file object was last modified. When a file object is [initialised or created](/CS1.2/api/access-service-api-v1-organisations-orggroupid-objects.md), this date and time should match (or be close to) that of the `createdAt` value below. Otherwise, if the file object has since been [modified](/CS1.2/api/access-service-api-v1-objects-objectid.md), this date and time should reflect when the file object was last modified. * **createdAt** - The date and time when the file object was first initialised or created, either in its *Incomplete* or *Created* states. * **labelName** - The name of the classification applied to the file object. Like **labelId** below, if this element's value is `null`, then no classification was specified (i.e. the **labelId** parameter was specified with an empty string or this parameter was omitted) when the file object was [initialised or created](/CS1.2/api/access-service-api-v1-organisations-orggroupid-objects.md), or [last updated](/CS1.2/api/access-service-api-v1-objects-objectid.md). This means that no classification restrictions (i.e. checks on Cocoon Data users' group membership and the association of these groups with individual classifications - see [User group endpoints](/CS1.2/api/user-group-endpoints.md) for more information) have been placed on collaborators added to this file object. * **type** - Indicates `object`, which in turn indicates that information about item returned from this request is about a file object. * **labelId** - The ID of the classification applied to the file object. If this element's value is `null`, then no classification was specified (i.e. the **labelId** parameter was specified with an empty string or this parameter was omitted) when the file object was [initialised or created](/CS1.2/api/access-service-api-v1-organisations-orggroupid-objects.md), or [last updated](/CS1.2/api/access-service-api-v1-objects-objectid.md). * **collaborators** - An array containing information about each Cocoon Data user who is currently a collaborator on this file object. Each element of this array contains information about one of these Cocoon Data users and is represented as an object, containing the following members: * **shareParentId** - Indicates either a value of `null` or `0`. A value of `null` indicates that the file object's location in its hierarchy of [folders](/CS1.2/api/folder-handling-endpoints.md) (e.g. as indicated in a SafeShare application's list of items) are equivalent between this collaborator (i.e. another Cocoon Data user account) and the current owner of this file object. A value of `0` indicates that the file object is being shared from the logical root file area/location of this collaborator's account. In SafeShare applications, this occurs when the owner of this file object has shared the file object with this collaborator, but the file object's parent folder has not also been shared with this collaborator. * **shareName** - Reserved for future use. Currently, this returns the value `null`. * **permissions** - An array listing the [permission set](/CS1.2/api/access-service-api-v1-permissions-sets.md) applied to this **collaborator** (or inherited by them from the location represented by **parentId**) on this file object, along with the individual permissions that constitue this permission set. * **email** - The collaborator's email address. * **firstName** - The collaborator's first name. This is the first name that appears on the [Users](/CS1.2/admin-org/administering-users-within-an-organisation.md) page of SafeShare Organisation Administration and the [My Account](/CS1.2/user/managing-your-account.md) feature of Cocoon Data SafeShare for Web. * **lastName** - The collaborator's last name. Like the first name (above), this appears on the **User** page of Organisation Administration and the **My Account** feature of SafeShare for Web. * **id** - The ID of the collaborator's Cocoon Data user account. **Note:** Only an empty array is returned from Cocoon Data user accounts who are collaborators on this file object *and* do not have the **View Other** [permission](/CS1.2/api/access-service-api-v1-permissions-sets.md) on it. \ **Example (response):** ```json theme={null} { "id": "734242448553197568", "shareStartTime": null, "shareEndTime": null, "shared": true, "name": "Executive Report.pdf", "sha512": "0X3iJ2keHhOBzrdJmUCw2QO0r7OOAwtaWDHGKU5cnkHVhdjeWtyvQAjjwAigT2dakgtM/BeZ/qvjuwAUtG9FdA==", "owner": { "email": "alex.originator@xy-company.com", "firstName": "Alex", "lastName": "Originator", "mfaEnabled": false, "id": "732856217122553856", "accountType": { "i18n": { "code": "server.useraccounttype.local", "arguments": [] }, "value": "LOCAL" } }, "hasView": false, "canGenerateView": true, "extension": "pdf", "organisation": { "name": "XY Company", "description": "", "mfaEnabled": false, "id": "732855142835470336" }, "permissions": [], "mimeType": null, "contentSize": "3596924", "parentId": "0", "originator": { "email": "alex.originator@xy-company.com", "id": "732856217122553856" }, "state": "server.object.states.created", "modifiedAt": "2016-07-19T02:58:55.534Z", "createdAt": "2016-07-19T02:57:21.300Z", "labelName": null, "type": "object", "labelId": null, "collaborators": [{ "shareParentId": null, "shareName": null, "permissionSet": null, "email": "chris.collaborator@xy-company.com", "firstName": "Chris", "lastName": "Collaborator", "id": "732856277868658688" }] } ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.