API

Files and spaces.

Spaces are how people open storage. A path is relative to the space, uses /, and has no leading slash. kind on a space is shared or personal. level is view, edit, or full. icon is folder, home, users, film, image, music, or briefcase. The older root-and-path calls still work.

Authentication, errors, and paging are in the API reference. Sending the key is described once there.

Spaces

`GET /api/v1/home`

The spaces this caller can open. Personal spaces come first.

Who. Any user with a key that has the read scope. A key with the admin scope includes the others. The key needs a license that includes the REST API.

Success. 200.

Field Type Meaning

spaces array of objects required

Each item is an object:

Field	Type		Meaning
`id`	string	required	The id.
`name`	string	required	The name.
`icon`	string	required	folder, home, users, film, image, music, or briefcase.
`kind`	string	required
`level`	string	required	`view`, `edit` or `full`. The best access this person has anywhere in the space.

anySpaces boolean required Whether this server has any space at all. An empty list means "nothing has been set up yet" when this is false and "none of it is yours" when it is true, and the two need different words.

{
  "spaces": [
    {
      "id": "k7Qm2sLp9vX4aB1c",
      "name": "Rush delivery",
      "icon": "folder",
      "kind": "shared",
      "level": "edit"
    }
  ],
  "anySpaces": true
}

Errors. The body always has the shape in Errors. Match on code.

Status	code	When
401	`unauthenticated`	no key, or a key that is unknown, expired, revoked, or owned by a disabled account
403	`forbidden`	the key is valid but does not have the scope, or an administrator route was called by someone who is not an administrator
402	`licence_required`	the license does not include the REST API

{
  "error": {
    "code": "unauthenticated",
    "message": "sign in to continue"
  }
}

Personal spaces are listed first. This is the call to make before you browse files.

`GET /api/v1/spaces/{id}`

One space: name, icon, kind and the caller's level. An administrator also gets the location's name.

Who. Any user with a key that has the read scope. A key with the admin scope includes the others. The key needs a license that includes the REST API.

Parameters.

Name	In	Type		Meaning
`id`	path	string	required	The resource's id.

Success. 200.

Field	Type		Meaning
`id`	string	required	The id.
`name`	string	required	The name.
`icon`	string	required	folder, home, users, film, image, music, or briefcase.
`kind`	string	required
`level`	string	required
`locationName`	string	optional, left out when empty

{
  "id": "k7Qm2sLp9vX4aB1c",
  "name": "Rush delivery",
  "icon": "folder",
  "kind": "shared",
  "level": "edit",
  "locationName": "example"
}

Errors. The body always has the shape in Errors. Match on code.

Status	code	When
404	`not_found`	not there, or not visible to this caller
401	`unauthenticated`	no key, or a key that is unknown, expired, revoked, or owned by a disabled account
403	`forbidden`	the key is valid but does not have the scope, or an administrator route was called by someone who is not an administrator
402	`licence_required`	the license does not include the REST API

{
  "error": {
    "code": "not_found",
    "message": "not found"
  }
}

`GET /api/v1/spaces/{id}/files`

One folder inside a space. Each entry has a level: view, edit, full, or traverse when the folder is only on the way to a grant.

Who. Any user with a key that has the read scope. A key with the admin scope includes the others. The key needs a license that includes the REST API.

Parameters.

Name	In	Type		Meaning
`id`	path	string	required	The space.
`path`	query	string	optional	Folder, relative to the space.

Encode the query value. A slash in a path may stay as / or be written %2F; the server reads the decoded value. Do not put a leading slash on the path.

Success. 200.

Field Type Meaning

path string required A path relative to the space or the storage location, with / between folders and no leading slash.

level string required

items array of objects required The records in this reply.

Each item is an object:

Field	Type		Meaning
`name`	string	required	The name.
`path`	string	required	A path relative to the space or the storage location, with / between folders and no leading slash.
`kind`	string	required
`size`	integer	required	Size in bytes.
`modified`	string	optional
`level`	string	required	`view`, `edit`, `full`, or `traverse` when the folder is only on the way to a grant further down.

{
  "path": "projects/rush",
  "level": "edit",
  "items": [
    {
      "name": "Rush delivery",
      "path": "projects/rush",
      "kind": "file",
      "size": 1048576,
      "modified": "example",
      "level": "edit"
    }
  ]
}

Errors. The body always has the shape in Errors. Match on code.

Status	code	When
400	`bad_request`	the request is not valid
401	`unauthenticated`	no key, or a key that is unknown, expired, revoked, or owned by a disabled account
403	`forbidden`	the key is valid but does not have the scope, or an administrator route was called by someone who is not an administrator
402	`licence_required`	the license does not include the REST API

{
  "error": {
    "code": "bad_request",
    "message": "the request is not valid"
  }
}

`DELETE /api/v1/spaces/{id}/files`

Delete a file or a folder inside a space.

Who. Any user with a key that has the delete scope. A key with the admin scope includes the others. The key needs a license that includes the REST API.

Parameters.

Name	In	Type		Meaning
`id`	path	string	required	The space.
`path`	query	string	optional	What to delete, relative to the space.

Encode the query value. A slash in a path may stay as / or be written %2F; the server reads the decoded value. Do not put a leading slash on the path.

Success. 200.

The reply has no body.

Errors. The body always has the shape in Errors. Match on code.

Status	code	When
400	`bad_request`	name a file or a folder
404	`not_found`	not there, or not visible to this caller
401	`unauthenticated`	no key, or a key that is unknown, expired, revoked, or owned by a disabled account
403	`forbidden`	the key is valid but does not have the scope, or an administrator route was called by someone who is not an administrator
402	`licence_required`	the license does not include the REST API

{
  "error": {
    "code": "bad_request",
    "message": "name a file or a folder"
  }
}

`POST /api/v1/spaces/{id}/folder`

Make a folder inside a space. Body: {path}.

Who. Any user with a key that has the write scope. A key with the admin scope includes the others. The key needs a license that includes the REST API.

Parameters.

Name	In	Type		Meaning
`id`	path	string	required	The resource's id.

Request body. JSON.

A field the server does not know is refused with 400.

Field	Type		Meaning
`path`	string	optional	A path relative to the space or the storage location, with / between folders and no leading slash.

{
  "path": "projects/rush"
}

Success. 200.

Field	Type		Meaning
`name`	string	required	The name.
`path`	string	required	A path relative to the space or the storage location, with / between folders and no leading slash.
`kind`	string	required
`size`	integer	required	Size in bytes.
`modified`	string	optional, left out when empty

{
  "name": "Rush delivery",
  "path": "projects/rush",
  "kind": "file",
  "size": 1048576,
  "modified": "example"
}

Errors. The body always has the shape in Errors. Match on code.

Status	code	When
400	`bad_request`	name the folder
409	`conflict`	something is already there
401	`unauthenticated`	no key, or a key that is unknown, expired, revoked, or owned by a disabled account
403	`forbidden`	the key is valid but does not have the scope, or an administrator route was called by someone who is not an administrator
402	`licence_required`	the license does not include the REST API

{
  "error": {
    "code": "bad_request",
    "message": "name the folder"
  }
}

`POST /api/v1/spaces/{id}/rename`

Rename or move inside a space. Body: {from, to}.

Who. Any user with a key that has the write scope. A key with the admin scope includes the others. The key needs a license that includes the REST API.

Parameters.

Name	In	Type		Meaning
`id`	path	string	required	The resource's id.

Request body. JSON.

A field the server does not know is refused with 400.

Field	Type		Meaning
`from`	string	optional
`to`	string	required

{
  "from": "projects/rush",
  "to": "projects/rush"
}

Success. 200.

Field	Type		Meaning
`name`	string	required	The name.
`path`	string	required	A path relative to the space or the storage location, with / between folders and no leading slash.
`kind`	string	required
`size`	integer	required	Size in bytes.
`modified`	string	optional, left out when empty

{
  "name": "Rush delivery",
  "path": "projects/rush",
  "kind": "file",
  "size": 1048576,
  "modified": "example"
}

Errors. The body always has the shape in Errors. Match on code.

Status	code	When
400	`bad_request`	name a file or a folder
409	`conflict`	something is already there
401	`unauthenticated`	no key, or a key that is unknown, expired, revoked, or owned by a disabled account
403	`forbidden`	the key is valid but does not have the scope, or an administrator route was called by someone who is not an administrator
402	`licence_required`	the license does not include the REST API

{
  "error": {
    "code": "bad_request",
    "message": "name a file or a folder"
  }
}

Managing spaces

`GET /api/v1/admin/spaces`

Every space, and storage locations that are not shared yet.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Success. 200.

Field Type Meaning

spaces array of objects required

Each item is an object:

Field	Type		Meaning
`id`	string	required	The id.
`name`	string	required	The name.
`icon`	string	required	folder, home, users, film, image, music, or briefcase.
`kind`	string	required
`rootId`	string	required	The id.
`basePath`	string	required
`template`	string	optional
`forGroup`	string	optional
`position`	integer	required
`createdAt`	string	required	A time, as RFC 3339.
`locationName`	string	required
`locationKind`	string	required
`locationPath`	string	required

unshared array of objects required

Each item is an object:

Field	Type		Meaning
`id`	string	required	The id.
`name`	string	required	The name.
`kind`	string	required

{
  "spaces": [
    {
      "id": "k7Qm2sLp9vX4aB1c",
      "name": "Rush delivery",
      "icon": "folder",
      "kind": "shared",
      "rootId": "k7Qm2sLp9vX4aB1c",
      "basePath": "projects/rush",
      "position": 1,
      "createdAt": "2026-10-05T18:00:00Z",
      "locationName": "example",
      "locationKind": "example",
      "locationPath": "projects/rush"
    }
  ],
  "unshared": [
    {
      "id": "k7Qm2sLp9vX4aB1c",
      "name": "Rush delivery",
      "kind": "shared"
    }
  ]
}

Errors. The body always has the shape in Errors. Match on code.

Status	code	When
401	`unauthenticated`	no key, or a key that is unknown, expired, revoked, or owned by a disabled account
403	`forbidden`	the key is valid but does not have the scope, or an administrator route was called by someone who is not an administrator
402	`licence_required`	the license does not include the REST API

{
  "error": {
    "code": "unauthenticated",
    "message": "sign in to continue"
  }
}

`POST /api/v1/admin/spaces`

Create a space. Body: {name, icon, rootId, basePath, kind: shared|personal, template, forGroup}.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Request body. JSON.

A field the server does not know is refused with 400.

Field	Type		Meaning
`name`	string	required	The name.
`icon`	string	optional	folder, home, users, film, image, music, or briefcase.
`rootId`	string	required	The id.
`basePath`	string	optional
`kind`	string	required
`template`	string	optional
`forGroup`	string	optional

{
  "name": "Rush delivery",
  "icon": "folder",
  "rootId": "k7Qm2sLp9vX4aB1c",
  "basePath": "projects/rush",
  "kind": "shared",
  "template": "example",
  "forGroup": "example"
}

Success. 200.

Field	Type		Meaning
`id`	string	required	The id.
`name`	string	required	The name.
`icon`	string	required	folder, home, users, film, image, music, or briefcase.
`kind`	string	required
`rootId`	string	required	The id.
`basePath`	string	required
`template`	string	optional
`forGroup`	string	optional
`position`	integer	required
`createdAt`	string	required	A time, as RFC 3339.
`locationName`	string	required
`locationKind`	string	required
`locationPath`	string	required

{
  "id": "k7Qm2sLp9vX4aB1c",
  "name": "Rush delivery",
  "icon": "folder",
  "kind": "shared",
  "rootId": "k7Qm2sLp9vX4aB1c",
  "basePath": "projects/rush",
  "position": 1,
  "createdAt": "2026-10-05T18:00:00Z",
  "locationName": "example",
  "locationKind": "example",
  "locationPath": "projects/rush"
}

Errors. The body always has the shape in Errors. Match on code.

Status	code	When
400	`bad_request`	the name, kind or template is not usable
409	`conflict`	the name is taken
401	`unauthenticated`	no key, or a key that is unknown, expired, revoked, or owned by a disabled account
403	`forbidden`	the key is valid but does not have the scope, or an administrator route was called by someone who is not an administrator
402	`licence_required`	the license does not include the REST API

{
  "error": {
    "code": "bad_request",
    "message": "the name, kind or template is not usable"
  }
}

`POST /api/v1/admin/spaces/preview`

The warnings a new space would raise, without saving it. Same body as creating one.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Request body. JSON.

A field the server does not know is refused with 400.

Field	Type		Meaning
`name`	string	required	The name.
`icon`	string	optional	folder, home, users, film, image, music, or briefcase.
`rootId`	string	required	The id.
`basePath`	string	optional
`kind`	string	required
`template`	string	optional
`forGroup`	string	optional

{
  "name": "Rush delivery",
  "icon": "folder",
  "rootId": "k7Qm2sLp9vX4aB1c",
  "basePath": "projects/rush",
  "kind": "shared",
  "template": "example",
  "forGroup": "example"
}

Success. 200.

Field	Type		Meaning
`warnings`	array of string	required

{
  "warnings": [
    "example"
  ]
}

Errors. The body always has the shape in Errors. Match on code.

Status	code	When
401	`unauthenticated`	no key, or a key that is unknown, expired, revoked, or owned by a disabled account
403	`forbidden`	the key is valid but does not have the scope, or an administrator route was called by someone who is not an administrator
402	`licence_required`	the license does not include the REST API

{
  "error": {
    "code": "unauthenticated",
    "message": "sign in to continue"
  }
}

`GET /api/v1/admin/spaces/{id}`

One space, including the location path. A personal space includes the people who have opened their folder.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Parameters.

Name	In	Type		Meaning
`id`	path	string	required	The resource's id.

Success. 200.

Field Type Meaning

space object required

It is an object:

Field	Type		Meaning
`id`	string	required	The id.
`name`	string	required	The name.
`icon`	string	required	folder, home, users, film, image, music, or briefcase.
`kind`	string	required
`rootId`	string	required	The id.
`basePath`	string	required
`template`	string	optional
`forGroup`	string	optional
`position`	integer	required
`createdAt`	string	required	A time, as RFC 3339.
`locationName`	string	required
`locationKind`	string	required
`locationPath`	string	required

people array of objects required

Each item is an object:

Field	Type		Meaning
`userId`	string	required	The id.
`email`	string	required	An email address.
`displayName`	string	required

{
  "space": {
    "id": "k7Qm2sLp9vX4aB1c",
    "name": "Rush delivery",
    "icon": "folder",
    "kind": "shared",
    "rootId": "k7Qm2sLp9vX4aB1c",
    "basePath": "projects/rush",
    "position": 1,
    "createdAt": "2026-10-05T18:00:00Z",
    "locationName": "example",
    "locationKind": "example",
    "locationPath": "projects/rush"
  },
  "people": [
    {
      "userId": "k7Qm2sLp9vX4aB1c",
      "email": "[email protected]",
      "displayName": "example"
    }
  ]
}

Errors. The body always has the shape in Errors. Match on code.

Status	code	When
401	`unauthenticated`	no key, or a key that is unknown, expired, revoked, or owned by a disabled account
403	`forbidden`	the key is valid but does not have the scope, or an administrator route was called by someone who is not an administrator
402	`licence_required`	the license does not include the REST API

{
  "error": {
    "code": "unauthenticated",
    "message": "sign in to continue"
  }
}

`PATCH /api/v1/admin/spaces/{id}`

Rename a space, change its icon or position, or change which group a personal space is for.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Parameters.

Name	In	Type		Meaning
`id`	path	string	required	The resource's id.

Request body. JSON.

A field the server does not know is refused with 400.

Field	Type		Meaning
`name`	string	optional	The name.
`icon`	string	optional	folder, home, users, film, image, music, or briefcase.
`position`	integer	optional
`forGroup`	string	optional

{
  "name": "Rush delivery",
  "icon": "folder",
  "position": 1,
  "forGroup": "example"
}

Success. 200.

Field	Type		Meaning
`id`	string	required	The id.
`name`	string	required	The name.
`icon`	string	required	folder, home, users, film, image, music, or briefcase.
`kind`	string	required
`rootId`	string	required	The id.
`basePath`	string	required
`template`	string	optional
`forGroup`	string	optional
`position`	integer	required
`createdAt`	string	required	A time, as RFC 3339.
`locationName`	string	required
`locationKind`	string	required
`locationPath`	string	required

{
  "id": "k7Qm2sLp9vX4aB1c",
  "name": "Rush delivery",
  "icon": "folder",
  "kind": "shared",
  "rootId": "k7Qm2sLp9vX4aB1c",
  "basePath": "projects/rush",
  "position": 1,
  "createdAt": "2026-10-05T18:00:00Z",
  "locationName": "example",
  "locationKind": "example",
  "locationPath": "projects/rush"
}

Errors. The body always has the shape in Errors. Match on code.

Status	code	When
401	`unauthenticated`	no key, or a key that is unknown, expired, revoked, or owned by a disabled account
403	`forbidden`	the key is valid but does not have the scope, or an administrator route was called by someone who is not an administrator
402	`licence_required`	the license does not include the REST API

{
  "error": {
    "code": "unauthenticated",
    "message": "sign in to continue"
  }
}

`DELETE /api/v1/admin/spaces/{id}`

Remove a space.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Access another shared space also holds moves to the innermost such space; all other access on the space is removed, and one space.deleted audit entry lists both. The files stay on the storage location. Jobs keep their location and path.

Parameters.

Name	In	Type		Meaning
`id`	path	string	required	The resource's id.

Success. 200.

The reply has no body.

Errors. The body always has the shape in Errors. Match on code.

Status	code	When
409	`conflict`	a personal space whose private folders shared access on the location would then reach
401	`unauthenticated`	no key, or a key that is unknown, expired, revoked, or owned by a disabled account
403	`forbidden`	the key is valid but does not have the scope, or an administrator route was called by someone who is not an administrator
402	`licence_required`	the license does not include the REST API

{
  "error": {
    "code": "conflict",
    "message": "a personal space whose private folders shared access on the location would then reach"
  }
}

`GET /api/v1/admin/spaces/{id}/removal`

What removing the space would do, without doing it: {name, kind, locationName, lose, keep, exposes}.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

lose is the access that would be removed, keep the access that would move to another space (with spaceId and spaceName), and exposes the shared access that stops a personal space from being removed.

Parameters.

Name	In	Type		Meaning
`id`	path	string	required	The resource's id.

Success. 200.

Field Type Meaning

name string required The name.

kind string required

locationName string required

lose array of objects required Access that goes with the space, because no other space holds its folder. Paths are relative to the space.

Each item is an object:

Field	Type		Meaning
`id`	string	required	The id.
`kind`	string	required
`principalId`	string	required	The id.
`principalName`	string	required
`path`	string	required	A path relative to the space or the storage location, with / between folders and no leading slash.
`level`	string	required

keep array of objects required Access another shared space also holds. It moves there and keeps working.

Each item is an object:

Field Type Meaning

access object required

It is an object:

Field	Type		Meaning
`id`	string	required	The id.
`kind`	string	required
`principalId`	string	required	The id.
`principalName`	string	required
`path`	string	required	A path relative to the space or the storage location, with / between folders and no leading slash.
`level`	string	required

spaceId string required The id.

spaceName string required

exposes array of objects required Shared access on the location that would reach into this personal space's private folders once the space no longer marks them as private. Paths are relative to the location. While there is any, the space is not removed.

Each item is an object:

Field	Type		Meaning
`id`	string	required	The id.
`kind`	string	required
`principalId`	string	required	The id.
`principalName`	string	required
`path`	string	required	A path relative to the space or the storage location, with / between folders and no leading slash.
`level`	string	required

{
  "name": "Rush delivery",
  "kind": "shared",
  "locationName": "example",
  "lose": [
    {
      "id": "k7Qm2sLp9vX4aB1c",
      "kind": "shared",
      "principalId": "k7Qm2sLp9vX4aB1c",
      "principalName": "example",
      "path": "projects/rush",
      "level": "edit"
    }
  ],
  "keep": [
    {
      "access": {
        "id": "k7Qm2sLp9vX4aB1c",
        "kind": "shared",
        "principalId": "k7Qm2sLp9vX4aB1c",
        "principalName": "example",
        "path": "projects/rush",
        "level": "edit"
      },
      "spaceId": "k7Qm2sLp9vX4aB1c",
      "spaceName": "example"
    }
  ],
  "exposes": [
    {
      "id": "k7Qm2sLp9vX4aB1c",
      "kind": "shared",
      "principalId": "k7Qm2sLp9vX4aB1c",
      "principalName": "example",
      "path": "projects/rush",
      "level": "edit"
    }
  ]
}

Errors. The body always has the shape in Errors. Match on code.

Status	code	When
401	`unauthenticated`	no key, or a key that is unknown, expired, revoked, or owned by a disabled account
403	`forbidden`	the key is valid but does not have the scope, or an administrator route was called by someone who is not an administrator
402	`licence_required`	the license does not include the REST API

{
  "error": {
    "code": "unauthenticated",
    "message": "sign in to continue"
  }
}

`GET /api/v1/admin/spaces/{id}/access`

Grants on this space, paths relative to the space.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Parameters.

Name	In	Type		Meaning
`id`	path	string	required	The resource's id.

Success. 200.

The body is an array.

Field	Type		Meaning
`id`	string	required	The id.
`kind`	string	required
`principalId`	string	required	The id.
`principalName`	string	required
`path`	string	required	A path relative to the space or the storage location, with / between folders and no leading slash.
`level`	string	required

[
  {
    "id": "k7Qm2sLp9vX4aB1c",
    "kind": "shared",
    "principalId": "k7Qm2sLp9vX4aB1c",
    "principalName": "example",
    "path": "projects/rush",
    "level": "edit"
  }
]

Errors. The body always has the shape in Errors. Match on code.

Status	code	When
401	`unauthenticated`	no key, or a key that is unknown, expired, revoked, or owned by a disabled account
403	`forbidden`	the key is valid but does not have the scope, or an administrator route was called by someone who is not an administrator
402	`licence_required`	the license does not include the REST API

{
  "error": {
    "code": "unauthenticated",
    "message": "sign in to continue"
  }
}

`PUT /api/v1/admin/spaces/{id}/access`

Give a person or a group view, edit or full access on the space or a folder in it.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Parameters.

Name	In	Type		Meaning
`id`	path	string	required	The resource's id.

Request body. JSON.

A field the server does not know is refused with 400.

Field	Type		Meaning
`userId`	string	optional	The id.
`groupId`	string	optional	The id.
`path`	string	optional	A path relative to the space or the storage location, with / between folders and no leading slash.
`access`	string	required

{
  "userId": "k7Qm2sLp9vX4aB1c",
  "groupId": "k7Qm2sLp9vX4aB1c",
  "path": "projects/rush",
  "access": "edit"
}

Success. 200.

Field	Type		Meaning
`id`	string	required	The id.
`kind`	string	required
`principalId`	string	required	The id.
`principalName`	string	required
`path`	string	required	A path relative to the space or the storage location, with / between folders and no leading slash.
`level`	string	required

{
  "id": "k7Qm2sLp9vX4aB1c",
  "kind": "shared",
  "principalId": "k7Qm2sLp9vX4aB1c",
  "principalName": "example",
  "path": "projects/rush",
  "level": "edit"
}

Errors. The body always has the shape in Errors. Match on code.

Status	code	When
400	`bad_request`	neither or both of userId and groupId, or a personal space
401	`unauthenticated`	no key, or a key that is unknown, expired, revoked, or owned by a disabled account
403	`forbidden`	the key is valid but does not have the scope, or an administrator route was called by someone who is not an administrator
402	`licence_required`	the license does not include the REST API

{
  "error": {
    "code": "bad_request",
    "message": "neither or both of userId and groupId, or a personal space"
  }
}

`DELETE /api/v1/admin/spaces/{id}/access/{grant_id}`

Take one space grant away.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Parameters.

Name	In	Type		Meaning
`id`	path	string	required	The space.
`grant_id`	path	string	required	The grant.

Success. 200.

The reply has no body.

Errors. The body always has the shape in Errors. Match on code.

Status	code	When
401	`unauthenticated`	no key, or a key that is unknown, expired, revoked, or owned by a disabled account
403	`forbidden`	the key is valid but does not have the scope, or an administrator route was called by someone who is not an administrator
402	`licence_required`	the license does not include the REST API

{
  "error": {
    "code": "unauthenticated",
    "message": "sign in to continue"
  }
}

`GET /api/v1/admin/spaces/{id}/personal/{user_id}/files`

Open one person's personal folder. Writes space.personal.opened to the audit log.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Parameters.

Name	In	Type		Meaning
`id`	path	string	required	The space.
`user_id`	path	string	required	The person.
`path`	query	string	optional	Folder, relative to their folder.

Encode the query value. A slash in a path may stay as / or be written %2F; the server reads the decoded value. Do not put a leading slash on the path.

Success. 200.

Field Type Meaning

path string required A path relative to the space or the storage location, with / between folders and no leading slash.

level string required

items array of objects required The records in this reply.

Each item is an object:

Field	Type		Meaning
`name`	string	required	The name.
`path`	string	required	A path relative to the space or the storage location, with / between folders and no leading slash.
`kind`	string	required
`size`	integer	required	Size in bytes.
`modified`	string	optional
`level`	string	required	`view`, `edit`, `full`, or `traverse` when the folder is only on the way to a grant further down.

{
  "path": "projects/rush",
  "level": "edit",
  "items": [
    {
      "name": "Rush delivery",
      "path": "projects/rush",
      "kind": "file",
      "size": 1048576,
      "modified": "example",
      "level": "edit"
    }
  ]
}

Errors. The body always has the shape in Errors. Match on code.

Status	code	When
400	`bad_request`	the request is not valid
401	`unauthenticated`	no key, or a key that is unknown, expired, revoked, or owned by a disabled account
403	`forbidden`	the key is valid but does not have the scope, or an administrator route was called by someone who is not an administrator
402	`licence_required`	the license does not include the REST API

{
  "error": {
    "code": "bad_request",
    "message": "the request is not valid"
  }
}

`GET /api/v1/admin/access/folder`

Who can reach this folder, and why.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Parameters.

Name	In	Type		Meaning
`space`	query	string	required	The space.
`path`	query	string	optional	Folder, relative to the space.

Encode the query value. A slash in a path may stay as / or be written %2F; the server reads the decoded value. Do not put a leading slash on the path.

Success. 200.

The body is an array.

Field	Type		Meaning
`kind`	string	required
`name`	string	required	The name.
`path`	string	required	A path relative to the space or the storage location, with / between folders and no leading slash.
`level`	string	required
`why`	string	required

[
  {
    "kind": "shared",
    "name": "Rush delivery",
    "path": "projects/rush",
    "level": "edit",
    "why": "example"
  }
]

Errors. The body always has the shape in Errors. Match on code.

Status	code	When
400	`bad_request`	the request is not valid
401	`unauthenticated`	no key, or a key that is unknown, expired, revoked, or owned by a disabled account
403	`forbidden`	the key is valid but does not have the scope, or an administrator route was called by someone who is not an administrator
402	`licence_required`	the license does not include the REST API

{
  "error": {
    "code": "bad_request",
    "message": "the request is not valid"
  }
}

`GET /api/v1/admin/users/{id}/access`

Every space and folder one person can reach, and why.

Who. An administrator, with a key that has the admin scope. An administrator's key that does not have that scope is refused. The key needs a license that includes the REST API.

Parameters.

Name	In	Type		Meaning
`id`	path	string	required	The resource's id.

Success. 200.

The body is an array.

Field Type Meaning

id string required The id.

name string required The name.

kind string required

paths array of objects required

Each item is an object:

Field	Type		Meaning
`kind`	string	required
`name`	string	required	The name.
`path`	string	required	A path relative to the space or the storage location, with / between folders and no leading slash.
`level`	string	required
`why`	string	required

[
  {
    "id": "k7Qm2sLp9vX4aB1c",
    "name": "Rush delivery",
    "kind": "shared",
    "paths": [
      {
        "kind": "shared",
        "name": "Rush delivery",
        "path": "projects/rush",
        "level": "edit",
        "why": "example"
      }
    ]
  }
]

Errors. The body always has the shape in Errors. Match on code.

Status	code	When
401	`unauthenticated`	no key, or a key that is unknown, expired, revoked, or owned by a disabled account
403	`forbidden`	the key is valid but does not have the scope, or an administrator route was called by someone who is not an administrator
402	`licence_required`	the license does not include the REST API

{
  "error": {
    "code": "unauthenticated",
    "message": "sign in to continue"
  }
}

Files and folders

`GET /api/v1/roots`

The storage locations this caller may see. Prefer GET /api/v1/home.

Still served, so an older script keeps working. New scripts should use spaces.

Who. Any user with a key that has the read scope. A key with the admin scope includes the others. The key needs a license that includes the REST API.

Success. 200.

The body is an array.

Field	Type		Meaning
`id`	string	required	The id.
`name`	string	required	The name.
`kind`	string	required
`canWrite`	boolean	required	What this caller may do anywhere in the storage location. The portal uses these to decide which buttons to draw; the server checks again per path, because a grant can cover one folder and not another.
`canDelete`	boolean	required

[
  {
    "id": "k7Qm2sLp9vX4aB1c",
    "name": "Rush delivery",
    "kind": "shared",
    "canWrite": true,
    "canDelete": true
  }
]

Errors. The body always has the shape in Errors. Match on code.

Status	code	When
401	`unauthenticated`	no key, or a key that is unknown, expired, revoked, or owned by a disabled account
403	`forbidden`	the key is valid but does not have the scope, or an administrator route was called by someone who is not an administrator
402	`licence_required`	the license does not include the REST API

{
  "error": {
    "code": "unauthenticated",
    "message": "sign in to continue"
  }
}

`GET /api/v1/files`

One folder's contents: {items, total, nextCursor}. Prefer a space.

Still served, so an older script keeps working. New scripts should use spaces.

Who. Any user with a key that has the read scope. A key with the admin scope includes the others. The key needs a license that includes the REST API.

Parameters.

Name	In	Type		Meaning
`root`	query	string	required	Which storage location.
`path`	query	string	optional	Folder, relative to the storage location. `/` separated, no leading slash.
`sort`	query	string	optional	name, size or modified. Defaults to name.
`dir`	query	string	optional	asc or desc. Defaults to asc.
`filter`	query	string	optional	Narrow the listing. Matched against the name, ignoring case.
`cursor`	query	string	optional	Where to resume: the previous reply's nextCursor. Omit to start.
`limit`	query	integer	optional	How many entries, from 1 to 1000. Defaults to 200.

Encode the query value. A slash in a path may stay as / or be written %2F; the server reads the decoded value. Do not put a leading slash on the path.

Success. 200.

Field Type Meaning

items array of objects required The records in this reply.

Each item is an object:

Field	Type		Meaning
`name`	string	required	The name.
`path`	string	required	A path relative to the space or the storage location, with / between folders and no leading slash.
`kind`	string	required
`size`	integer	required	Size in bytes.
`modified`	string	optional

total integer required How many matched, including ones not on this page.

nextCursor string optional Send this back as cursor to get the next page. Left out when this is the last page.

{
  "items": [
    {
      "name": "Rush delivery",
      "path": "projects/rush",
      "kind": "file",
      "size": 1048576,
      "modified": "example"
    }
  ],
  "total": 1,
  "nextCursor": "example"
}

Errors. The body always has the shape in Errors. Match on code.

Status	code	When
400	`bad_request`	the request is not valid
401	`unauthenticated`	no key, or a key that is unknown, expired, revoked, or owned by a disabled account
403	`forbidden`	the key is valid but does not have the scope, or an administrator route was called by someone who is not an administrator
402	`licence_required`	the license does not include the REST API

{
  "error": {
    "code": "bad_request",
    "message": "the request is not valid"
  }
}

The cursor is how many entries to skip after sorting, from the previous nextCursor. limit defaults to 200 and must be from 1 to 1000. A folder this caller may not see is 404, the same answer as a folder that is not there.

`DELETE /api/v1/files`

Delete a file or a folder. Body: {root, path}.

Who. Any user with a key that has the delete scope. A key with the admin scope includes the others. The key needs a license that includes the REST API.

Request body. JSON.

Field	Type		Meaning
`root`	string	required
`path`	string	required	A path relative to the space or the storage location, with / between folders and no leading slash.

{
  "root": "k7Qm2sLp9vX4aB1c",
  "path": "projects/rush"
}

Success. 200.

The reply has no body.

Errors. The body always has the shape in Errors. Match on code.

Status	code	When
400	`bad_request`	the request is not valid
404	`not_found`	not there, or this caller may not delete it
401	`unauthenticated`	no key, or a key that is unknown, expired, revoked, or owned by a disabled account
403	`forbidden`	the key is valid but does not have the scope, or an administrator route was called by someone who is not an administrator
402	`licence_required`	the license does not include the REST API

{
  "error": {
    "code": "bad_request",
    "message": "the request is not valid"
  }
}

`POST /api/v1/files/folder`

Make a folder.

Who. Any user with a key that has the write scope. A key with the admin scope includes the others. The key needs a license that includes the REST API.

Request body. JSON.

Field	Type		Meaning
`root`	string	required
`path`	string	required	A path relative to the space or the storage location, with / between folders and no leading slash.

{
  "root": "k7Qm2sLp9vX4aB1c",
  "path": "projects/rush"
}

Success. 200.

Field	Type		Meaning
`name`	string	required	The name.
`path`	string	required	A path relative to the space or the storage location, with / between folders and no leading slash.
`kind`	string	required
`size`	integer	required	Size in bytes.
`modified`	string	optional, left out when empty

{
  "name": "Rush delivery",
  "path": "projects/rush",
  "kind": "file",
  "size": 1048576,
  "modified": "example"
}

Errors. The body always has the shape in Errors. Match on code.

Status	code	When
400	`bad_request`	the request is not valid
409	`conflict`	something is already there
404	`not_found`	not there, or not visible to this caller
401	`unauthenticated`	no key, or a key that is unknown, expired, revoked, or owned by a disabled account
403	`forbidden`	the key is valid but does not have the scope, or an administrator route was called by someone who is not an administrator
402	`licence_required`	the license does not include the REST API

{
  "error": {
    "code": "bad_request",
    "message": "the request is not valid"
  }
}

`POST /api/v1/files/rename`

Rename or move within a storage location.

Who. Any user with a key that has the write scope. A key with the admin scope includes the others. The key needs a license that includes the REST API.

Request body. JSON.

Field	Type
`root`	string	required
`from`	string	required
`to`	string	required

{
  "root": "k7Qm2sLp9vX4aB1c",
  "from": "projects/rush",
  "to": "projects/rush"
}

Success. 200.

Field	Type		Meaning
`name`	string	required	The name.
`path`	string	required	A path relative to the space or the storage location, with / between folders and no leading slash.
`kind`	string	required
`size`	integer	required	Size in bytes.
`modified`	string	optional, left out when empty

{
  "name": "Rush delivery",
  "path": "projects/rush",
  "kind": "file",
  "size": 1048576,
  "modified": "example"
}

Errors. The body always has the shape in Errors. Match on code.

Status	code	When
400	`bad_request`	the request is not valid
409	`conflict`	something is already there
404	`not_found`	not there, or not visible to this caller
401	`unauthenticated`	no key, or a key that is unknown, expired, revoked, or owned by a disabled account
403	`forbidden`	the key is valid but does not have the scope, or an administrator route was called by someone who is not an administrator
402	`licence_required`	the license does not include the REST API

{
  "error": {
    "code": "bad_request",
    "message": "the request is not valid"
  }
}