Workspaces API

Version: 1.0

Preview

Get folder by ID

GET

/workspace/orgs/{org_id}/workspaces/{workspace_id}/folders/{folder_id}

Preview API

This API functionality is currently in preview. Preview APIs may be unstable within the preview period: they may change without notice. You must set the header API-Preview: opt-in to opt into using this functionality.

Returns a folder by its ID. Optionally include its child folders up to a specified depth.

Request

Path parameters

org_iduuid

Required

workspace_iduuid

Required

folder_iduuid

Required

Query parameters

limitinteger

Default: 5000

Max number of results per page.

offsetinteger

Number of results to skip before returning limit number of results.

deletedboolean

Only show folders that have been deleted.

max_depthinteger

Max depth of the folder tree to return with the folder.

folder_namestring | null

<= 116 chars

Examples: "folder_name", "eq:folder_name", "like:folder_name", "ilike:folder_name"

Only show folders with a matching name. This filter supports the operators eq, like, and ilike. If no operator is provided, the eq operator is used. The eq operator performs an exact string match while the like and ilike operators support pattern matching (regular expressions). The only difference between like and ilike is that ilike searches case-insensitive. For example, you can use like:a to find any folder that contain the lower case 'a' or ilike:a to find any folder containing the letter 'A' or 'a'.

created_bystring[] | null

Only show folders created by user

created_atstring | null

<= 36 chars

Examples: "2023-10-01T00:00:00", "gt:2023-10-01T00:00:00Z", "2023-10-01T00:00:00+12:00"

Only show folders relative to the creation date. This filter supports operators like gt, lt, gte, and lte. For example, you can use 2023-10-01T00:00:000 for exact match or gt:2023-10-01 for greater than. Supported formats are ISO 8601 date strings.

updated_bystring[] | null

Only show folders modified by user

updated_atstring | null

<= 36 chars

Examples: "2023-10-01T00:00:00", "gt:2023-10-01T00:00:00Z", "2023-10-01T00:00:00+12:00"

Only show folders relative to the creation date. This filter supports operators like gt, lt, gte, and lte. For example, you can use 2023-10-01T00:00:000 for exact match or gt:2023-10-01 for greater than. Supported formats are ISO 8601 date strings.

order_bystring

(1, 128) chars

A comma separated list of fields to order by, where the default sort order is ascending. To specify the sort order, prefix the field name with either asc: or desc: for ascending or descending respectively. Field names can be one of the following known sort fields: created_at, updated_at, name

Responses

200

Successful Response

Response schema

child_foldersChildFolderListResponse

countinteger

foldersFolderResponse[]

created_atdate-time

created_byUserModel

Optional

emailstring | null

iduuid

namestring | null

deletedboolean

folder_iduuid

namestring

parent_folder_iduuid | null

pathpath

updated_atdate-time

updated_byUserModel

Optional

emailstring | null

iduuid

namestring | null

workspace_iduuid

limitinteger

offsetinteger

totalinteger

folderFolderResponse

created_atdate-time

created_byUserModel

emailstring | null

iduuid

namestring | null

deletedboolean

folder_iduuid

namestring

parent_folder_iduuid | null

pathpath

updated_atdate-time

updated_byUserModel

emailstring | null

iduuid

namestring | null

workspace_iduuid

Example response

{
  "child_folders": {
    "count": 0,
    "folders": [
      {
        "created_at": "2024-07-29T15:51:28.071Z",
        "created_by": {
          "email": "string",
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "name": "string"
        },
        "deleted": true,
        "folder_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "string",
        "parent_folder_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "path": "string",
        "updated_at": "2024-07-29T15:51:28.071Z",
        "updated_by": {
          "email": "string",
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "name": "string"
        },
        "workspace_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      }
    ],
    "limit": 0,
    "offset": 0,
    "total": 0
  },
  "folder": {
    "created_at": "2024-07-29T15:51:28.071Z",
    "created_by": {
      "email": "string",
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "string"
    },
    "deleted": true,
    "folder_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "string",
    "parent_folder_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "path": "string",
    "updated_at": "2024-07-29T15:51:28.071Z",
    "updated_by": {
      "email": "string",
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "string"
    },
    "workspace_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

401

No permission -- see authorization schemes

Response schema

detailstring | null

invalid-paramsErrorInvalidParam[] | null

statusinteger

titlestring

typestring

Example response

{
  "detail": "string",
  "invalid-params": [
    {
      "name": "string",
      "reason": "string"
    }
  ],
  "status": 0,
  "title": "string",
  "type": "string"
}

403

Request forbidden -- authorization will not help

Response schema

detailstring | null

invalid-paramsErrorInvalidParam[] | null

statusinteger

titlestring

typestring

Example response

{
  "detail": "string",
  "invalid-params": [
    {
      "name": "string",
      "reason": "string"
    }
  ],
  "status": 0,
  "title": "string",
  "type": "string"
}

404

Resource not found or user lacks access

Response schema

detailstring | null

invalid-paramsErrorInvalidParam[] | null

statusinteger

titlestring

typestring

Example response

{
  "detail": "string",
  "invalid-params": [
    {
      "name": "string",
      "reason": "string"
    }
  ],
  "status": 0,
  "title": "string",
  "type": "string"
}

405

Specified method is invalid for this resource

Response schema

detailstring | null

invalid-paramsErrorInvalidParam[] | null

statusinteger

titlestring

typestring

Example response

{
  "detail": "string",
  "invalid-params": [
    {
      "name": "string",
      "reason": "string"
    }
  ],
  "status": 0,
  "title": "string",
  "type": "string"
}

410

Resource is gone

Response schema

detailstring | null

invalid-paramsErrorInvalidParam[] | null

statusinteger

titlestring

typestring

Example response

{
  "detail": "string",
  "invalid-params": [
    {
      "name": "string",
      "reason": "string"
    }
  ],
  "status": 0,
  "title": "string",
  "type": "string"
}

422

Unprocessable Content

Response schema

detailstring | null

invalid-paramsErrorInvalidParam[] | null

statusinteger

titlestring

typestring

Example response

{
  "detail": "string",
  "invalid-params": [
    {
      "name": "string",
      "reason": "string"
    }
  ],
  "status": 0,
  "title": "string",
  "type": "string"
}