List the company folders of the drive

GET

/drives/{drive}/shares

const url = 'https://work.optidata.cloud/api/drives/1/shares';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://work.optidata.cloud/api/drives/1/shares \
  --header 'Authorization: Bearer <token>'

Alias of GET /drives/{drive} — the same payload under the name the file manager uses for its shares screen.

Authorizations

bearerAuth

Parameters

Path Parameters

drive

required

integer format: int64

Numeric id of the drive. Read it from GET /drives/config.json.

Responses

200

The company folders of the drive.

application/json

object

shares

required

Array<object>

The sharing record of a node, holding every permission granted on it.

object

integer format: int64

drive_id

integer format: int64

node_id

integer format: int64

user_id

Owner of the share.

integer format: int64

cuid

string

node_type

integer

Allowed values: 1 2

link_hash

Set once a public link is enabled for the share.

string | null

link_share_url

string | null format: uri

permissions

Array<object>

One grant inside a share. Exactly one of user_id or group_id is set; the link permission has both null.

object

integer format: int64

share_id

integer format: int64

user_id

integer | null format: int64

group_id

integer | null format: int64

actions

Permission level granted. share and owner are legacy aliases of manage.

string

Allowed values: none view edit share owner manage

valid_for_seconds

Lifetime of a link permission in seconds; -1 means never expires.

integer | null

is_download_allowed

boolean | null

is_upload_allowed

boolean | null

is_email_confirmation_required

boolean | null

is_password_protected

boolean | null

created_at

string format: date-time

updated_at

string format: date-time

link_share_permission

One of:

object
null

One grant inside a share. Exactly one of user_id or group_id is set; the link permission has both null.

object

integer format: int64

share_id

integer format: int64

user_id

integer | null format: int64

group_id

integer | null format: int64

actions

Permission level granted. share and owner are legacy aliases of manage.

string

Allowed values: none view edit share owner manage

valid_for_seconds

Lifetime of a link permission in seconds; -1 means never expires.

integer | null

is_download_allowed

boolean | null

is_upload_allowed

boolean | null

is_email_confirmation_required

boolean | null

is_password_protected

boolean | null

created_at

string format: date-time

updated_at

string format: date-time

users

Array<object>

A user of the tenant.

object

integer format: int64

uuid

string format: uuid

cuid

Identifier of the company (tenant) the user belongs to.

string

username

string

email

string format: email

name

string

full_name

string

company_name

string

role

Role of the user inside the tenant.

string

status

string

Allowed values: active inactive blocked

avatar_url

string | null format: uri

created_at

string format: date-time

updated_at

string format: date-time

deleted_at

string | null format: date-time

profile

Profile extras (avatar, job title). Loaded only where noted.

object | null

groups

Groups the user belongs to. Loaded only where noted.

Array<object>

A group of users inside the tenant.

object

integer format: int64

guid

Tenant-wide identifier of the group; used in paths.

string format: uuid

name

string

description

string | null

email

string | null format: email

cuid

string

memberships

Members of the group, each with its embedded user.

Array<object>

object

key

additional properties

any

userStatus

Presence status of the user. Loaded only where noted.

object | null

status_details

Rendered presence details (type, icon, message). Present on dashboard listings.

object | null

groups

Array<object>

A group of users inside the tenant.

object

integer format: int64

guid

Tenant-wide identifier of the group; used in paths.

string format: uuid

name

string

description

string | null

email

string | null format: email

cuid

string

memberships

Members of the group, each with its embedded user.

Array<object>

object

key

additional properties

any

node

A file or a folder. type is 1 for a folder and 2 for a file; the booleans is_folder / is_file are derived from it. Content attributes (content_*) are null on folders and on files that have no bytes yet.

object

required

integer format: int64

parent_id

Parent folder id. null marks a company folder (top level).

integer | null format: int64

drive_id

required

integer format: int64

user_id

Owner of the node.

integer format: int64

uuid

string

cuid

string

type

required

1 = folder, 2 = file.

integer

Allowed values: 1 2

name

required

string

is_folder

boolean

is_file

boolean

is_coeditable

Whether the file can be co-edited in the online editor.

boolean

is_cold

Whether the node lives in cold storage. Present only on detail reads.

boolean

is_delete_target

true when this node was the explicit target of a delete; null when it was removed only because an ancestor was deleted.

boolean | null

ltree_path

Materialised ancestor path, dot separated ids.

string | null

group_id

integer | null format: int64

node_content_id

Current content version of the file.

integer | null format: int64

oldest_node_content_id

integer | null format: int64

guest_data_id

integer | null format: int64

content_path

string | null

content_mime_type

string | null

content_size_bytes

integer | null format: int64

content_thumbnail_url

string | null format: uri

content

One of:

object
null

One stored version of a file’s bytes.

object

integer format: int64

node_id

integer format: int64

path

Opaque storage path of this content version.

string

mime_type

string

size_bytes

integer format: int64

hash_sha256

SHA-256 of this version, the value a caller sends back as base_content_hash.

string | null

base_content_hash

The hash_sha256 of the version this one was written from, as sent in base_content_hash and accepted by the server. null when the write carried no base. Equal to the hash a sync client last committed: the other side edited that version. Different, or null: the client cannot tell, and should keep a conflict copy.

string | null

created_at

string format: date-time

updated_at

string format: date-time

actions

The caller’s effective permission level on this node. Present on listings derived from shares.

string

Allowed values: none view edit share owner manage

user

One of:

object
null

A user of the tenant.

object

integer format: int64

uuid

string format: uuid

cuid

Identifier of the company (tenant) the user belongs to.

string

username

string

email

string format: email

name

string

full_name

string

company_name

string

role

Role of the user inside the tenant.

string

status

string

Allowed values: active inactive blocked

avatar_url

string | null format: uri

created_at

string format: date-time

updated_at

string format: date-time

deleted_at

string | null format: date-time

profile

Profile extras (avatar, job title). Loaded only where noted.

object | null

groups

Groups the user belongs to. Loaded only where noted.

Array<object>

A group of users inside the tenant.

object

integer format: int64

guid

Tenant-wide identifier of the group; used in paths.

string format: uuid

name

string

description

string | null

email

string | null format: email

cuid

string

memberships

Members of the group, each with its embedded user.

Array<object>

object

key

additional properties

any

userStatus

Presence status of the user. Loaded only where noted.

object | null

status_details

Rendered presence details (type, icon, message). Present on dashboard listings.

object | null

customization

Per-node presentation settings (colour, shared flag).

object | null

markers

Array<object>

A per-user flag on a node.

object

integer format: int64

node_id

integer format: int64

user_id

integer format: int64

type

Kind of marker.

string

Allowed values: favorite important

created_at

string format: date-time

tags

Array<object>

object

key

additional properties

any

lock

One of:

object
null

An advisory lock held on a file while it is being edited. Take one before replacing the content of a file another user could be working on.

object

integer format: int64

node_id

integer format: int64

user_id

integer format: int64

note

Free-text reason shown to other users.

string | null

origin

Free-text label naming the client that took the lock.

string | null

user_hash

Opaque per-installation identifier of the lock holder.

string | null

expires_at

string | null format: date-time

created_at

string format: date-time

updated_at

string format: date-time

user

One of:

object
null

A user of the tenant.

object

integer format: int64

uuid

string format: uuid

cuid

Identifier of the company (tenant) the user belongs to.

string

username

string

email

string format: email

name

string

full_name

string

company_name

string

role

Role of the user inside the tenant.

string

status

string

Allowed values: active inactive blocked

avatar_url

string | null format: uri

created_at

string format: date-time

updated_at

string format: date-time

deleted_at

string | null format: date-time

profile

Profile extras (avatar, job title). Loaded only where noted.

object | null

groups

Groups the user belongs to. Loaded only where noted.

Array<object>

A group of users inside the tenant.

object

integer format: int64

guid

Tenant-wide identifier of the group; used in paths.

string format: uuid

name

string

description

string | null

email

string | null format: email

cuid

string

memberships

Members of the group, each with its embedded user.

Array<object>

object

key

additional properties

any

userStatus

Presence status of the user. Loaded only where noted.

object | null

status_details

Rendered presence details (type, icon, message). Present on dashboard listings.

object | null

locks

Array<object>

An advisory lock held on a file while it is being edited. Take one before replacing the content of a file another user could be working on.

object

integer format: int64

node_id

integer format: int64

user_id

integer format: int64

note

Free-text reason shown to other users.

string | null

origin

Free-text label naming the client that took the lock.

string | null

user_hash

Opaque per-installation identifier of the lock holder.

string | null

expires_at

string | null format: date-time

created_at

string format: date-time

updated_at

string format: date-time

user

One of:

object
null

A user of the tenant.

object

integer format: int64

uuid

string format: uuid

cuid

Identifier of the company (tenant) the user belongs to.

string

username

string

email

string format: email

name

string

full_name

string

company_name

string

role

Role of the user inside the tenant.

string

status

string

Allowed values: active inactive blocked

avatar_url

string | null format: uri

created_at

string format: date-time

updated_at

string format: date-time

deleted_at

string | null format: date-time

profile

Profile extras (avatar, job title). Loaded only where noted.

object | null

groups

Groups the user belongs to. Loaded only where noted.

Array<object>

A group of users inside the tenant.

object

integer format: int64

guid

Tenant-wide identifier of the group; used in paths.

string format: uuid

name

string

description

string | null

email

string | null format: email

cuid

string

memberships

Members of the group, each with its embedded user.

Array<object>

object

key

additional properties

any

userStatus

Presence status of the user. Loaded only where noted.

object | null

status_details

Rendered presence details (type, icon, message). Present on dashboard listings.

object | null

created_at

string format: date-time

updated_at

string format: date-time

deleted_at

Non-null while the node is in the trash.

string | null format: date-time

created_at

string format: date-time

updated_at

string format: date-time

folders

required

Array<object>

object

required

integer format: int64

parent_id

Parent folder id. null marks a company folder (top level).

integer | null format: int64

drive_id

required

integer format: int64

user_id

Owner of the node.

integer format: int64

uuid

string

cuid

string

type

required

1 = folder, 2 = file.

integer

Allowed values: 1 2

name

required

string

is_folder

boolean

is_file

boolean

is_coeditable

Whether the file can be co-edited in the online editor.

boolean

is_cold

Whether the node lives in cold storage. Present only on detail reads.

boolean

is_delete_target

true when this node was the explicit target of a delete; null when it was removed only because an ancestor was deleted.

boolean | null

ltree_path

Materialised ancestor path, dot separated ids.

string | null

group_id

integer | null format: int64

node_content_id

Current content version of the file.

integer | null format: int64

oldest_node_content_id

integer | null format: int64

guest_data_id

integer | null format: int64

content_path

string | null

content_mime_type

string | null

content_size_bytes

integer | null format: int64

content_thumbnail_url

string | null format: uri

content

One of:

object
null

One stored version of a file’s bytes.

object

integer format: int64

node_id

integer format: int64

path

Opaque storage path of this content version.

string

mime_type

string

size_bytes

integer format: int64

hash_sha256

SHA-256 of this version, the value a caller sends back as base_content_hash.

string | null

base_content_hash

string | null

created_at

string format: date-time

updated_at

string format: date-time

actions

The caller’s effective permission level on this node. Present on listings derived from shares.

string

Allowed values: none view edit share owner manage

user

One of:

object
null

A user of the tenant.

object

integer format: int64

uuid

string format: uuid

cuid

Identifier of the company (tenant) the user belongs to.

string

username

string

email

string format: email

name

string

full_name

string

company_name

string

role

Role of the user inside the tenant.

string

status

string

Allowed values: active inactive blocked

avatar_url

string | null format: uri

created_at

string format: date-time

updated_at

string format: date-time

deleted_at

string | null format: date-time

profile

Profile extras (avatar, job title). Loaded only where noted.

object | null

groups

Groups the user belongs to. Loaded only where noted.

Array<object>

A group of users inside the tenant.

object

integer format: int64

guid

Tenant-wide identifier of the group; used in paths.

string format: uuid

name

string

description

string | null

email

string | null format: email

cuid

string

memberships

Members of the group, each with its embedded user.

Array<object>

object

key

additional properties

any

userStatus

Presence status of the user. Loaded only where noted.

object | null

status_details

Rendered presence details (type, icon, message). Present on dashboard listings.

object | null

customization

Per-node presentation settings (colour, shared flag).

object | null

markers

Array<object>

A per-user flag on a node.

object

integer format: int64

node_id

integer format: int64

user_id

integer format: int64

type

Kind of marker.

string

Allowed values: favorite important

created_at

string format: date-time

tags

Array<object>

object

key

additional properties

any

lock

One of:

object
null

An advisory lock held on a file while it is being edited. Take one before replacing the content of a file another user could be working on.

object

integer format: int64

node_id

integer format: int64

user_id

integer format: int64

note

Free-text reason shown to other users.

string | null

origin

Free-text label naming the client that took the lock.

string | null

user_hash

Opaque per-installation identifier of the lock holder.

string | null

expires_at

string | null format: date-time

created_at

string format: date-time

updated_at

string format: date-time

user

One of:

object
null

A user of the tenant.

object

integer format: int64

uuid

string format: uuid

cuid

Identifier of the company (tenant) the user belongs to.

string

username

string

email

string format: email

name

string

full_name

string

company_name

string

role

Role of the user inside the tenant.

string

status

string

Allowed values: active inactive blocked

avatar_url

string | null format: uri

created_at

string format: date-time

updated_at

string format: date-time

deleted_at

string | null format: date-time

profile

Profile extras (avatar, job title). Loaded only where noted.

object | null

groups

Groups the user belongs to. Loaded only where noted.

Array<object>

A group of users inside the tenant.

object

integer format: int64

guid

Tenant-wide identifier of the group; used in paths.

string format: uuid

name

string

description

string | null

email

string | null format: email

cuid

string

memberships

Members of the group, each with its embedded user.

Array<object>

object

key

additional properties

any

userStatus

Presence status of the user. Loaded only where noted.

object | null

status_details

Rendered presence details (type, icon, message). Present on dashboard listings.

object | null

locks

Array<object>

An advisory lock held on a file while it is being edited. Take one before replacing the content of a file another user could be working on.

object

integer format: int64

node_id

integer format: int64

user_id

integer format: int64

note

Free-text reason shown to other users.

string | null

origin

Free-text label naming the client that took the lock.

string | null

user_hash

Opaque per-installation identifier of the lock holder.

string | null

expires_at

string | null format: date-time

created_at

string format: date-time

updated_at

string format: date-time

user

One of:

object
null

A user of the tenant.

object

integer format: int64

uuid

string format: uuid

cuid

Identifier of the company (tenant) the user belongs to.

string

username

string

email

string format: email

name

string

full_name

string

company_name

string

role

Role of the user inside the tenant.

string

status

string

Allowed values: active inactive blocked

avatar_url

string | null format: uri

created_at

string format: date-time

updated_at

string format: date-time

deleted_at

string | null format: date-time

profile

Profile extras (avatar, job title). Loaded only where noted.

object | null

groups

Groups the user belongs to. Loaded only where noted.

Array<object>

A group of users inside the tenant.

object

integer format: int64

guid

Tenant-wide identifier of the group; used in paths.

string format: uuid

name

string

description

string | null

email

string | null format: email

cuid

string

memberships

Members of the group, each with its embedded user.

Array<object>

object

key

additional properties

any

userStatus

Presence status of the user. Loaded only where noted.

object | null

status_details

Rendered presence details (type, icon, message). Present on dashboard listings.

object | null

created_at

string format: date-time

updated_at

string format: date-time

deleted_at

Non-null while the node is in the trash.

string | null format: date-time

files

required

Array<object>

object

required

integer format: int64

parent_id

Parent folder id. null marks a company folder (top level).

integer | null format: int64

drive_id

required

integer format: int64

user_id

Owner of the node.

integer format: int64

uuid

string

cuid

string

type

required

1 = folder, 2 = file.

integer

Allowed values: 1 2

name

required

string

is_folder

boolean

is_file

boolean

is_coeditable

Whether the file can be co-edited in the online editor.

boolean

is_cold

Whether the node lives in cold storage. Present only on detail reads.

boolean

is_delete_target

true when this node was the explicit target of a delete; null when it was removed only because an ancestor was deleted.

boolean | null

ltree_path

Materialised ancestor path, dot separated ids.

string | null

group_id

integer | null format: int64

node_content_id

Current content version of the file.

integer | null format: int64

oldest_node_content_id

integer | null format: int64

guest_data_id

integer | null format: int64

content_path

string | null

content_mime_type

string | null

content_size_bytes

integer | null format: int64

content_thumbnail_url

string | null format: uri

content

One of:

object
null

One stored version of a file’s bytes.

object

integer format: int64

node_id

integer format: int64

path

Opaque storage path of this content version.

string

mime_type

string

size_bytes

integer format: int64

hash_sha256

SHA-256 of this version, the value a caller sends back as base_content_hash.

string | null

base_content_hash

string | null

created_at

string format: date-time

updated_at

string format: date-time

actions

The caller’s effective permission level on this node. Present on listings derived from shares.

string

Allowed values: none view edit share owner manage

user

One of:

object
null

A user of the tenant.

object

integer format: int64

uuid

string format: uuid

cuid

Identifier of the company (tenant) the user belongs to.

string

username

string

email

string format: email

name

string

full_name

string

company_name

string

role

Role of the user inside the tenant.

string

status

string

Allowed values: active inactive blocked

avatar_url

string | null format: uri

created_at

string format: date-time

updated_at

string format: date-time

deleted_at

string | null format: date-time

profile

Profile extras (avatar, job title). Loaded only where noted.

object | null

groups

Groups the user belongs to. Loaded only where noted.

Array<object>

A group of users inside the tenant.

object

integer format: int64

guid

Tenant-wide identifier of the group; used in paths.

string format: uuid

name

string

description

string | null

email

string | null format: email

cuid

string

memberships

Members of the group, each with its embedded user.

Array<object>

object

key

additional properties

any

userStatus

Presence status of the user. Loaded only where noted.

object | null

status_details

Rendered presence details (type, icon, message). Present on dashboard listings.

object | null

customization

Per-node presentation settings (colour, shared flag).

object | null

markers

Array<object>

A per-user flag on a node.

object

integer format: int64

node_id

integer format: int64

user_id

integer format: int64

type

Kind of marker.

string

Allowed values: favorite important

created_at

string format: date-time

tags

Array<object>

object

key

additional properties

any

lock

One of:

object
null

An advisory lock held on a file while it is being edited. Take one before replacing the content of a file another user could be working on.

object

integer format: int64

node_id

integer format: int64

user_id

integer format: int64

note

Free-text reason shown to other users.

string | null

origin

Free-text label naming the client that took the lock.

string | null

user_hash

Opaque per-installation identifier of the lock holder.

string | null

expires_at

string | null format: date-time

created_at

string format: date-time

updated_at

string format: date-time

user

One of:

object
null

A user of the tenant.

object

integer format: int64

uuid

string format: uuid

cuid

Identifier of the company (tenant) the user belongs to.

string

username

string

email

string format: email

name

string

full_name

string

company_name

string

role

Role of the user inside the tenant.

string

status

string

Allowed values: active inactive blocked

avatar_url

string | null format: uri

created_at

string format: date-time

updated_at

string format: date-time

deleted_at

string | null format: date-time

profile

Profile extras (avatar, job title). Loaded only where noted.

object | null

groups

Groups the user belongs to. Loaded only where noted.

Array<object>

A group of users inside the tenant.

object

integer format: int64

guid

Tenant-wide identifier of the group; used in paths.

string format: uuid

name

string

description

string | null

email

string | null format: email

cuid

string

memberships

Members of the group, each with its embedded user.

Array<object>

object

key

additional properties

any

userStatus

Presence status of the user. Loaded only where noted.

object | null

status_details

Rendered presence details (type, icon, message). Present on dashboard listings.

object | null

locks

Array<object>

An advisory lock held on a file while it is being edited. Take one before replacing the content of a file another user could be working on.

object

integer format: int64

node_id

integer format: int64

user_id

integer format: int64

note

Free-text reason shown to other users.

string | null

origin

Free-text label naming the client that took the lock.

string | null

user_hash

Opaque per-installation identifier of the lock holder.

string | null

expires_at

string | null format: date-time

created_at

string format: date-time

updated_at

string format: date-time

user

One of:

object
null

A user of the tenant.

object

integer format: int64

uuid

string format: uuid

cuid

Identifier of the company (tenant) the user belongs to.

string

username

string

email

string format: email

name

string

full_name

string

company_name

string

role

Role of the user inside the tenant.

string

status

string

Allowed values: active inactive blocked

avatar_url

string | null format: uri

created_at

string format: date-time

updated_at

string format: date-time

deleted_at

string | null format: date-time

profile

Profile extras (avatar, job title). Loaded only where noted.

object | null

groups

Groups the user belongs to. Loaded only where noted.

Array<object>

A group of users inside the tenant.

object

integer format: int64

guid

Tenant-wide identifier of the group; used in paths.

string format: uuid

name

string

description

string | null

email

string | null format: email

cuid

string

memberships

Members of the group, each with its embedded user.

Array<object>

object

key

additional properties

any

userStatus

Presence status of the user. Loaded only where noted.

object | null

status_details

Rendered presence details (type, icon, message). Present on dashboard listings.

object | null

created_at

string format: date-time

updated_at

string format: date-time

deleted_at

Non-null while the node is in the trash.

string | null format: date-time

Examples

{
  "shares": [
    {
      "id": 2743,
      "drive_id": 1,
      "node_id": 300754,
      "user_id": 15,
      "link_hash": null,
      "node_type": 1,
      "link_share_url": null,
      "users": [],
      "groups": []
    }
  ],
  "folders": [
    {
      "id": 300754,
      "parent_id": null,
      "drive_id": 1,
      "type": 1,
      "name": "Contracts",
      "is_folder": true,
      "is_file": false,
      "is_cold": false
    }
  ],
  "files": []
}

401

Missing, malformed or expired authentication key.

application/json

Authentication failures use an error key rather than message.

object

error

required

string

Examples

missing

No bearer token sent

{
  "error": "JWT passport exception: Missing bearer token in request"
}

404

The resource does not exist, or does not belong to the given drive.

application/json

Generic error envelope used by policy, binding and framework failures.

object

message

required

Human-readable description of the failure.

string

Examples

missing

{
  "message": "No query results for model [App\\Models\\Node] 99999999"
}

429

Rate limit exceeded. Retry after the window resets.

application/json

Generic error envelope used by policy, binding and framework failures.

object

message

required

Human-readable description of the failure.

string

Examples

throttled

{
  "message": "Too Many Attempts."
}