API Reference

REST API

Version 2.0

Get Folder

GET/api/v2/filesystem/folders/{folderRid}

Warning

This endpoint is in preview and may be modified or removed at any time. To use this endpoint, add preview=true to the request query parameters.

Get the Folder with the specified rid.

Third-party applications using this endpoint via OAuth2 must request the following operation scope: api:filesystem-read.

Path parameters

folderRid

string

The unique resource identifier (RID) of a Folder.

Query parameters

preview

boolean

optional

Enables the use of preview functionality.

Response body

Folder

object

Hide child attributes

rid

string

The unique resource identifier (RID) of a Folder.

displayName

string

The display name of the Resource

description

string

optional

The description associated with the Folder.

documentation

string

optional

The documentation associated with the Folder.

path

string

The full path to the resource, including the resource name itself

type

string (enum)

A folder can be a regular Folder, a Project or a Space.

Enum values: FOLDER, SPACE, PROJECT

createdBy

string

The Foundry user who created this resource

updatedBy

string

The Foundry user who last updated this resource

createdTime

string

The time at which the resource was created.

updatedTime

string

The time at which the resource was most recently updated.

trashStatus

string (enum)

The trash status of the Folder. If trashed, this could either be because the Folder itself has been trashed or because one of its ancestors has been trashed.

Enum values: DIRECTLY_TRASHED, ANCESTOR_TRASHED, NOT_TRASHED

parentFolderRid

string

The parent folder Resource Identifier (RID). For Projects, this will be the Space RID and for Spaces, this value will be the root folder (ri.compass.main.folder.0).

projectRid

string

optional

The Project Resource Identifier (RID) that the Folder lives in. If the Folder is a Space, this value will not be defined.

spaceRid

string

The Space Resource Identifier (RID) that the Folder lives in. If the Folder is a Space, this value will be the same as the Folder RID.

Examples

Request

Copied!

curl \
\t-H "Authorization: Bearer $TOKEN" \
	"https://$HOSTNAME/api/v2/filesystem/folders/ri.compass.main.folder.01a79a9d-e293-48db-a585-9ffe221536e8?preview=true"

Response

Copied!

{
  "projectRid": "ri.compass.main.folder.4cae7c13-b59f-48f6-9ef2-dbde603e4e33",
  "updatedTime": "2024-09-25T17:29:35.974Z",
  "updatedBy": "f05f8da4-b84c-4fca-9c77-8af0b13d11de",
  "displayName": "My Folder",
  "description": "This dataset contains important data about Empyrean Airlines",
  "rid": "ri.compass.main.folder.01a79a9d-e293-48db-a585-9ffe221536e8",
  "type": "FOLDER",
  "spaceRid": "ri.compass.main.folder.a86ad5f5-3db5-48e4-9fdd-00aa3e5731ca",
  "trashStatus": "NOT_TRASHED",
  "parentFolderRid": "ri.compass.main.folder.4cae7c13-b59f-48f6-9ef2-dbde603e4e33",
  "path": "/Empyrean Airlines/My Important Project/My Folder",
  "createdBy": "f05f8da4-b84c-4fca-9c77-8af0b13d11de",
  "createdTime": "2024-09-25T17:29:35.974Z"
}

Error responses

Error Name
`InvalidFolder`	Error Code	`INVALID_ARGUMENT`
	Status Code	400
	Description	The given Resource is not a Folder.
	Parameters	`resourceRid`
`GetRootFolderNotSupported`	Error Code	`INVALID_ARGUMENT`
	Status Code	400
	Description	Getting the root folder as a resource is not supported.
	Parameters
`FolderNotFound`	Error Code	`NOT_FOUND`
	Status Code	404
	Description	The given Folder could not be found.
	Parameters	`folderRid`

See Errors for a general overview of errors in the platform.