Folders¶

Folders provide a way to group data, with the primary intention being to enable shared folders of data between different EveryPoint users. Once you create a folder, you can assign files to that folder, such that when you retrieve the list of files in the folder, only those files that have been added will appear.

Unlike a standard file system, a file can belong to multiple folders, which allows data to be grouped in various ways. Additionally, assigning a file to a folder does not prevent it from being returned in the results of a query that was performed on the instance. To restate this point, performing a query on a folder of files will only return files in that folder, whereas performing a query on an instance will return any files from that instance (regardless of whether or not the files have been assigned to folders).

For reference, the ability to group data is not unique to folders. In the case that a file is assigned to at most one folder, you could achieve a similar grouping behavior via custom attributes and query parameters. For example, you could create a custom attribute called "folder", and then query for files that match the desired folder name. In this manner, you could mimic the behavior of folders, without leveraging the /folders endpoint.

Supported file types and endpoints¶

A folder contains the necessary endpoints to store, query, and manipulate files. The list of supported file types and endpoints are listed here, where each endpoint has the same behavior as its corresponding version within an instance:

Images via the /images endpoint.
Videos via the /videos endpoint.
AR sessions via the /ar-sessions endpoint.
AR lidar sessions via the /ar-lidar-sessions endpoint.
Point clouds via the /point-clouds endpoint.
Meshes via the /meshes endpoint.
Orthomosaics via the /orthomosaics endpoint.

Folders¶

Get a list of folders¶

Returns a list of available folders. Each folder in the list is represented by its URI.

Route: /v3{instance-uri}/folders
Method: GET

Sample response body:

{
  "success": true,
  "data": {
    "folders": [
      "/folders/customer-abc",
      "/folders/shared-data"
    ]
  }
}

Get details of a folder¶

Retrieve the details of an individual folder.

Route: /v3{instance-uri}{folder-uri}
Method: GET

Sample response body:

{
  "success": true,
  "data": {
    "folder": {
      "uri": "/folders/customer-abc",
      "name": "customer-abc",
      "description": "Folder containing data for customer ABC."
    }
  }
}

Create a folder¶

Create a new folder.

Route: /v3{instance-uri}/folders
Method: POST

When creating a folder, a name and description must be provided. The name of the folder is limited to lowercase letters, numbers, and hyphens.

Sample request body:

{
  "name": "customer-abc",
  "description": "Folder containing data for customer ABC."
}

Upon successful creation of a folder, the response will contain the details of the newly created folder.

Update a folder¶

Update the name or description of a folder.

Route: /v3{instance-uri}{folder-uri}
Method: PATCH

The name or description of a folder can be updated via a PATCH request, where the body of the request contains the new name and/or description.

Sample request body:

{
  "name": "customer-abcd",
  "description": "Folder containing data for customer ABCD."
}

Upon successfully updating a folder, the response will contain the updated details of the folder.

Delete a folder¶

Delete a folder.

If the folder to be deleted is owned by the current user, then any data contained within the folder will still be accessible by the current user when the folder is deleted. However, any separate EveryPoint user who had shared access to this folder will lose access to the shared data. Similarly, if the deleted folder was a shared folder that was shared with you from another user, then deleting the folder will cause you to lose access to the shared data (but the other user will still have access to all of their data).

Route: /v3{instance-uri}{folder-uri}
Method: DELETE

Sample response body:

{
  "success": true
}

Add files to a folder¶

Add one or more files to a folder. Files to be added are represented by their URIs.

Route: /v3{instance-uri}{folder-uri}/add
Method: PATCH

Sample request body:

{
  "files": [
    "/images/1234-5678",
    "/videos/2345-6789"
  ]
}

Sample response body:

{
  "success": true
}

In the case that a new file is being uploaded, the file can be added to a folder by directly uploading the file to a supported file endpoint within the folder. Additionally, the folders form parameter can be used to assign a file to multiple folders when the file is being uploaded.

Remove files from a folder¶

Remove one or more files from a folder. Files to be removed are represented by their URIs.

Route: /v3{instance-uri}{folder-uri}/remove
Method: PATCH

Sample request body:

{
  "files": [
    "/images/1234-5678",
    "/videos/2345-6789"
  ]
}

Sample response body:

{
  "success": true
}

Shared folders¶

A shared folder provides the ability to share a set of files between two different EveryPoint instances or users. At a high level, one user will create a folder of files, and then share that folder with another user in a read-only fashion. The other user will be able to see that folder of files, and will be able to use them for whatever they want, but the other user will not be able to modify, add, or remove the set of files.

To describe the process in more detail, here is a list of the steps involved in sharing data between two instances or users:

The first user creates a folder in their instance and then adds the files to the folder that they intend to share.
The first user optionally sets one or more of their custom attributes to be shared, so that the second user will be able to see the values of those custom attributes when the files are actually shared.
The first user creates a new share for the folder, and sends the share_id and password to the second user.
The second user connects to the share using the share_id and password.
The second user now has a new folder within their instance which contains the set of shared files.

Additional details about shared data:

Standard attributes are always available when accessed via a shared folder (in contrast to custom attributes, which must have a shared property set to true).
A share can only be connected to and used a single time. If a folder should be shared with multiple users, then a new share should be created for each user that should have access to the shared folder.
Shared folders of data from another user are read-only. The user who originally created the shared folder can continue to add, remove, or modify the files in the folder, but the user who has connected to that shared folder cannot modify it in any way.
When a user deletes a share, the user who connected to the shared folder via that share will immediately lose access to the shared data. Similarly, when a user deletes a folder, any users who had connected to shares created for that folder will immediately lose access to the shared data.
When using a shared custom attribute as a query parameter, the query parameter name needs to be prefixed with the name of the shared folder (in order to differentiate it from a custom attribute that may have been created with the same name by the current user).
URIs for files and custom attributes within a shared folder from another account will be prefixed with the shared folder's URI (to indicate that these files and custom attributes originate with the shared folder). However, this URI convention should be transparent to the user, as the API is agnostic to the internal construction of a URI (e.g. a job can be created using URIs for both shared and non-shared files).

Get a list of shares¶

Returns a list of shares that have been created for a folder. Each share in the list is represented by its URI.

Route: /v3{instance-uri}{folder-uri}/shares
Method: GET

Sample response body:

{
  "success": true,
  "data": {
    "shares": [
      "/folders/my-folder/shares/1234-5678",
      "/folders/my-folder/shares/2345-6789"
    ]
  }
}

Retrieve the details of an individual share.

Route: /v3{instance-uri}{share-uri}
Method: GET

The share_id and password values in the response are used to enable separate EveryPoint users to connect to the shared folder.

Sample response body:

{
  "success": true,
  "data": {
    "share": {
      "uri": "/folders/my-folder/shares/1234-5678",
      "name": "My shared folder",
      "share_id": "2345-6789",
      "password": "abcd-efgh"
    }
  }
}

Create a new share for a folder.

Route: /v3{instance-uri}{folder-uri}/shares
Method: POST

When creating a new share, a name must be provided.

Sample request body:

{
  "name": "Shared folder with customer ABC."
}

Upon successful creation of a share, the response will contain the details of the newly created share.

Delete a share.

Any separate EveryPoint user who had shared access to this folder will lose access to the shared data.

Route: /v3{instance-uri}{share-uri}
Method: DELETE

Sample response body:

{
  "success": true
}

Connect to a shared folder. A share can only be used a single time, so once an EveryPoint user has connected to a share, no other users can use the same share to connect to the folder. Additional shares will need to be created in order to allow additional users to connect to the same shared folder.

Route: /v3{instance-uri}/connect-shared-folder
Method: POST

To connect to a shared folder, the share_id and password for the share need to be provided (obtained from the details of a share). The result of connecting to a share is the creation of a new folder within the user's account, so the name and description for that new folder also need to be provided.

Sample request body:

{
  "share_id": "2345-6789",
  "password": "abcd-efgh",
  "name": "shared-data",
  "description": "A shared folder with customer ABC."
}

Upon a successful connection to the shared folder, the response will contain the details of the newly created folder.

Messages¶

Messages are a way to send information to other EveryPoint users in order to enable coordination around shared data. To send a message between users, those users must have a shared folder between them (it does not matter which user shares the folder and which connects to it). Using the shared folder, one user can send a message to that folder, and the other will receive the message as a webhook call. For more information, refer to the details on sending a message.

As an example, suppose one user sends the following message to the shared folder:

{
  "message": "This is a message."
}

The other user will then receive a webhook call similar to the following, where the "folder" has been set to the full URL of the shared folder in the receiving user's account:

{
  "message": {
    "folder": "https://api.everypoint.io/v3{instance-uri}{folder-uri}",
    "body": "This is a message."
  }
}

Send a message¶

Send a message to a folder, and deliver that message to the webhook of any user with whom the folder is shared.

The contents of a message are stored as a string. It is up to the users of the shared folder to determine the format and conventions that should be used for the messages. For example, one common approach may be to decide upon a common JSON representation, and then send messages that are JSON-encoded strings of that representation.

When sending a message to a folder, the recipients of a message are determined as follows:

If the folder is not a shared folder, then no users receive the message.
If the user sending the message also owns the folder (i.e. they were the one that created the share), then any user who connected to that shared folder will receive the message.
If the user sending the message does not own the folder (i.e. they connected to the share), then only the owner of the folder (the user who created the share) will receive the message.

Route: /v3{instance-uri}{folder-uri}/send-message
Method: POST

Sample request body:

{
  "message": "This is a message."
}

Sample response body:

{
  "success": true
}

Folders¶

Supported file types and endpoints¶

Folders¶

Get a list of folders¶

Get details of a folder¶

Create a folder¶

Update a folder¶

Delete a folder¶

Add files to a folder¶

Remove files from a folder¶

Shared folders¶

Get a list of shares¶

Get details of a share¶

Create a share¶

Delete a share¶

Connect to a share¶

Messages¶

Send a message¶