Create a file or folder at the top level

POST

/drives/{drive}/nodes

const url = 'https://work.optidata.cloud/api/drives/1/nodes';
const form = new FormData();
form.append('name', 'Contracts');
form.append('type', '1');
form.append('file', 'file');
form.append('content', 'example');
form.append('mime_type', 'example');
form.append('hash_sha256', 'example');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

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

curl --request POST \
  --url https://work.optidata.cloud/api/drives/1/nodes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form name=Contracts \
  --form type=1 \
  --form file=@file \
  --form content=example \
  --form mime_type=example \
  --form hash_sha256=example

Same contract as POST /drives/{drive}/nodes/{node}, but the new node is created at the top level of the drive (as a company folder) rather than inside an existing folder.

Authorizations

bearerAuth

Parameters

Path Parameters

drive

required

integer format: int64

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

Request Body^required

Body of a node creation. Send type: 1 for a folder. For a file send type: 2 plus the bytes — file as a multipart upload, or content inline.

object

name

required

Name of the node. Trimmed of surrounding whitespace; must not collide with a sibling and must not contain characters the storage layer forbids.

string

type

required

1 = folder, 2 = file.

integer

Allowed values: 1 2

file

The file bytes, when posting multipart/form-data.

string | null format: binary

content

The file bytes inline, as an alternative to file.

string | null

mime_type

MIME type of the content, when it cannot be detected.

string | null

hash_sha256

SHA-256 of the content, for verification.

string | null

Body of a node creation. Send type: 1 for a folder. For a file send type: 2 plus the bytes — file as a multipart upload, or content inline.

object

name

required

Name of the node. Trimmed of surrounding whitespace; must not collide with a sibling and must not contain characters the storage layer forbids.

string

type

required

1 = folder, 2 = file.

integer

Allowed values: 1 2

file

The file bytes, when posting multipart/form-data.

string | null format: binary

content

The file bytes inline, as an alternative to file.

string | null

mime_type

MIME type of the content, when it cannot be detected.

string | null

hash_sha256

SHA-256 of the content, for verification.

string | null

Examples

companyFolder

{
  "name": "Contracts",
  "type": 1
}

Responses

200

The created node.

application/json

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

Example

{
  "id": 300754,
  "drive_id": 1,
  "type": 1,
  "name": "Contracts",
  "ltree_path": "300754.665198",
  "content_mime_type": "application/pdf",
  "content_size_bytes": 148213,
  "content": {
    "id": 613488,
    "mime_type": "application/pdf",
    "size_bytes": 148213
  },
  "actions": "none",
  "user": {
    "id": 15,
    "uuid": "9c1f0e2a-4d31-4d8a-8c1a-1f0b6b1f9a10",
    "cuid": "a1b2c3d4-2226-46c1-91b2-a9e9ba4c2d5b",
    "username": "jane.doe@acme.example",
    "email": "jane.doe@acme.example",
    "name": "Jane Doe",
    "full_name": "Jane Doe",
    "company_name": "Acme",
    "role": "super-admin",
    "status": "active",
    "groups": [
      {
        "id": 560,
        "guid": "a19d5670-335d-4285-8ee4-fcb54cb70faf",
        "name": "Finance"
      }
    ]
  },
  "markers": [
    {
      "type": "favorite"
    }
  ],
  "lock": {
    "user": {
      "id": 15,
      "uuid": "9c1f0e2a-4d31-4d8a-8c1a-1f0b6b1f9a10",
      "cuid": "a1b2c3d4-2226-46c1-91b2-a9e9ba4c2d5b",
      "username": "jane.doe@acme.example",
      "email": "jane.doe@acme.example",
      "name": "Jane Doe",
      "full_name": "Jane Doe",
      "company_name": "Acme",
      "role": "super-admin",
      "status": "active",
      "groups": [
        {
          "id": 560,
          "guid": "a19d5670-335d-4285-8ee4-fcb54cb70faf",
          "name": "Finance"
        }
      ]
    }
  },
  "locks": [
    {
      "user": {
        "id": 15,
        "uuid": "9c1f0e2a-4d31-4d8a-8c1a-1f0b6b1f9a10",
        "cuid": "a1b2c3d4-2226-46c1-91b2-a9e9ba4c2d5b",
        "username": "jane.doe@acme.example",
        "email": "jane.doe@acme.example",
        "name": "Jane Doe",
        "full_name": "Jane Doe",
        "company_name": "Acme",
        "role": "super-admin",
        "status": "active",
        "groups": [
          {
            "id": 560,
            "guid": "a19d5670-335d-4285-8ee4-fcb54cb70faf",
            "name": "Finance"
          }
        ]
      }
    }
  ]
}

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"
}

403

The caller lacks the permission level the operation requires.

application/json

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

object

message

required

Human-readable description of the failure.

string

Examples

denied

{
  "message": "This action is unauthorized."
}

422

The request body or query string failed validation.

application/json

object

message

required

The first validation message.

string

errors

required

Validation messages keyed by field name.

object

key

additional properties

Array<string>

Examples

invalid

{
  "message": "The name field is required.",
  "errors": {
    "name": [
      "The name field is required."
    ]
  }
}

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."
}

Create a file or folder at the top level

Authorizations

Parameters

Path Parameters

Request Bodyrequired

Examples

Responses

200

Example

401

Examples

403

Examples

422

Examples

429

Examples

Request Body^required