Folders API

Operations on folders. Folders and files share the resource model, the listing endpoint, and the folder tree described in Common conventions; this page covers what applies to folders only.

Base URL and scope

/api/external/v1/folders

Read operations need api:read. Upload, delete, rename, and move additionally need api:write.

Permission checks

When a folder belongs to another user, each operation checks the permission that user granted you:

Operation	Permission checked
Upload	UPLOAD on the destination folder
Rename	EDIT on the folder
Move	UPLOAD on the destination folder and EDIT on the folder being moved
Download	DOWNLOAD on the folder

A folder that is not shared with you fails with PERMISSION_001, and a missing permission fails with PERMISSION_002.

Upload a folder

Requires api:write

POST /api/external/v1/folders

Parameter	Type	Required	Description
fn	string	Yes	Folder name, up to 255 characters
pfs	long	No	Parent folder seq; required when ss is sent
ss	integer	No	Sharing user seq

Create folder

curl -X POST "https://drive.example.com/api/external/v1/folders" \
  -H "Authorization: Bearer replace-with-your-USER-API-KEY" \
  -H "Content-Type: application/json" \
  -d '{"pfs": 5, "fn": "Contracts"}'

Create folder response

{
  "result": true,
  "code": 201,
  "message": "Created",
  "data": {
    "resourceSeq": 2056,
    "resourceName": "Contracts"
  }
}

Omitting pfs creates the folder at the drive root. If the parent already holds a folder with the same name, the request does not fail: the folder is created under a numbered name. Read resourceName in the response for the name that was actually used. To check a name beforehand, use the name-collision endpoint in Common conventions.

Rename a folder

Requires api:write

PATCH /api/external/v1/folders/{resourceSeq}/rename

Parameter	Type	Required	Description
resourceSeq	long	Yes	Path parameter - the folder to rename
rn	string	Yes	New name, up to 255 characters
ss	integer	No	Sharing user seq; required for a shared folder
pfs	long	No	Parent folder seq; required for any folder not at the root, shared or not

Rename folder

curl -X PATCH "https://drive.example.com/api/external/v1/folders/{resourceSeq}/rename" \
  -H "Authorization: Bearer replace-with-your-USER-API-KEY" \
  -H "Content-Type: application/json" \
  -d '{"ss": 21, "pfs": 5, "rn": "Signed contracts"}'

pfs is the parent the service checks for a duplicate name. If you omit it, the check runs against the root instead.

Unlike upload, rename does not number a duplicate name. If the parent already holds a folder with the same name, the request fails with RESOURCE_006 (409). Unlike the file rename endpoint, there is no name-collision policy parameter.

Rename folder failure

{
  "result": false,
  "code": 409,
  "errorCode": "RESOURCE_006",
  "message": "..."
}

Move a folder

Requires api:write

POST /api/external/v1/folders/{resourceSeq}/move

Parameter	Type	Required	Description
resourceSeq	long	Yes	Path parameter - the folder to move
ts	integer	No	Target user seq; required when moving into another user's folder. Defaults to you
pfs	long	No	Destination (new parent) folder seq; required when ts is not you. Omitting it moves the folder to the root
ss	integer	No	Sharing user seq

Move folder

curl -X POST "https://drive.example.com/api/external/v1/folders/{resourceSeq}/move" \
  -H "Authorization: Bearer replace-with-your-USER-API-KEY" \
  -H "Content-Type: application/json" \
  -d '{"ts": 1, "ss": 21, "pfs": 5}'

Moving a folder moves everything inside it. A folder cannot move into one of its own subfolders or into the parent it is already in; either fails with RESOURCE_002. A locked folder fails with RESOURCE_LOCK_ASPECT_002 (423).

Move folder failure

{
  "result": false,
  "code": 400,
  "errorCode": "RESOURCE_002",
  "message": "..."
}

Delete a folder

Requires api:write

PATCH /api/external/v1/folders/{resourceSeq}/delete

Parameter	Type	Required	Description
resourceSeq	long	Yes	Path parameter - the folder to delete

The folder and its contents move to the trash rather than being removed. A failed delete returns RESOURCE_001.

Only folders you own can be deleted, which is why there is no ss parameter. A folder shared with you fails with RESOURCE_005, and a locked folder fails with RESOURCE_LOCK_ASPECT_002 (423).

Delete folder failure

{
  "result": false,
  "code": 423,
  "errorCode": "RESOURCE_LOCK_ASPECT_002",
  "message": "..."
}

Download a folder

A folder downloads as a ZIP archive in two steps. First issue a token with the API Key:

GET /api/external/v1/folders/{resourceSeq}/download-token

Header	Required	Value
Authorization	Yes	Bearer followed by the API Key

Parameter	Type	Required	Description
resourceSeq	long	Yes	Path parameter - the folder to download
ss	integer	No	Sharing user seq

Issue folder download token

curl "https://drive.example.com/api/external/v1/folders/{resourceSeq}/download-token" \
  -H "Authorization: Bearer replace-with-your-USER-API-KEY"

Folder token response

{
  "result": true,
  "code": 200,
  "message": "OK",
  "data": {
    "linkUrl": "/folders/download?dt={token}"
  }
}

linkUrl is a relative path. Resolve it against the Drive host the user is signed in to and send the browser there, for example https://drive.example.com/folders/download?dt={dt}. This browser request needs no API Key. Do not call /api/external/v1/folders/download instead: that path requires the API Key as a bearer token and does not fit the browser hand-off.

GET /folders/download?dt={dt}

The response is the ZIP binary stream, not the common JSON envelope:

HTTP 200 OK
Content-Type: application/zip
Content-Disposition: attachment; filename="archive.zip"

Pinned folders

A user can pin folders for quick access. Pinned folders are per-user and limited to three.

Pinning uses the read scope

Registering and deleting a pinned folder is not treated as a write operation. A key holding only api:read can change the pinned list.

List pinned folders

GET /api/external/v1/pinned-folders

Takes no parameters. Results are ordered by when they were pinned. A pinned entry disappears from the list automatically when the underlying folder is deleted.

Field	Type	Meaning
pinnedFolderSeq	long	Identifier of the pin, used to remove it
resourceSeq	long	The pinned folder
sharedByUserSeq	integer	The user who owns the folder; your own user seq for your own folder
resourceName	string	Folder name
resourceType	enum	Always FOLDER

Pin a folder

POST /api/external/v1/pinned-folders

Parameter	Type	Required	Description
rs	long	Yes	Folder resource seq; passing a file seq fails with RESOURCE_005
ss	integer	No	User seq of the folder owner; required when pinning a folder shared with you

Pin folder

curl -X POST "https://drive.example.com/api/external/v1/pinned-folders" \
  -H "Authorization: Bearer replace-with-your-USER-API-KEY" \
  -H "Content-Type: application/json" \
  -d '{"rs": 17466, "ss": 43}'

View permission on the folder is checked. A folder that is not shared with you fails with PERMISSION_001, and one you cannot access fails with PERMISSION_002. Pinning the same folder twice fails with PINNED_FOLDER_002, and going past three pins fails with PINNED_FOLDER_003.

Remove a pin

DELETE /api/external/v1/pinned-folders/{pinnedFolderSeq}

Parameter	Type	Required	Description
pinnedFolderSeq	long	Yes	Path parameter - the pin to remove

Removing a pin someone else owns, or one that is already gone, returns PINNED_FOLDER_001. The folder itself is not affected.

Errors

A failed request returns the common failure envelope:

Failure envelope

{
  "result": false,
  "code": 400,
  "errorCode": "REQUEST_001",
  "message": "..."
}

errorCode	HTTP	Meaning
REQUEST_001	400	Request validation failed
RESOURCE_001	400	Delete failed
RESOURCE_002	400	Move failed, including a move into the folder's own subfolder or current parent
RESOURCE_005	404	Resource not found, or a folder you do not own on delete
RESOURCE_006	409	A folder with the new name already exists in the parent
PERMISSION_001	403	The folder is not shared with you
PERMISSION_002	403	Missing permission on the folder
RESOURCE_LOCK_ASPECT_002	423	The folder is locked
AUTH_009	403	Invalid API Key or insufficient scope
RESPONSE_001	500	Server error

See Errors for the codes shared across the API.