zpe-files · zpe API

POST /_/api/v1/copy Copy a file or a whole folder to another path postCopy

Copy a file or a whole folder to another path

Parameters

name	in	required	type	notes
`from`	query	no	string	The file or folder to copy. Send it here or as `from` in a JSON body.
`overwrite`	query	no	boolean	Replace the destination when it already exists. Default false.
`to`	query	no	string	Where the copy goes. Send it here or as `to` in a JSON body.

Request body

None: this operation takes its arguments in the path and the query.

Responses

status	meaning	body
`200`	The file was copied. `from` still exists: a copy does not move it.	object
`400`	`from` or `to` is missing, is not a usable key, names the internal prefix, is the same as the other, or sits inside it; or the JSON body could not be read.	object
`401`	The credential is missing or does not open this account	object
`403`	This account may not do that: the key's scope does not cover this method, or the door's grant does not name this app	object
`404`	`from` names nothing in this account's prefix.	object
`409`	`to` is already there and `overwrite` was not asked for.	object
`429`	Too many requests: this key has spent its request ceiling, and `Retry-After` says when to come back	object
`500`	This app failed while answering	object
`503`	A service this app needs did not answer — the door could not be reached, so this request was not checked	object

Example

Copy a file or a whole folder to another path, with a token from the door.

POST /_/api/v1/copy

curl -X POST 'https://zpe.vc/files/_/api/v1/copy?from=string&overwrite=false&to=string' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

200 application/json

{}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

POST /_/api/v1/counts Count the direct children of one or more folders postCounts

Count the direct children of one or more folders

Parameters

No parameters.

Request body

None: this operation takes its arguments in the path and the query.

Responses

status	meaning	body
`200`	One count per folder, keyed by path. A folder that could not be counted is absent rather than zero, so a missing key means `unknown`, not `empty`.	object
`400`	The JSON body could not be read, so there were no folders to count.	object
`401`	The credential is missing or does not open this account	object
`403`	This account may not do that: the key's scope does not cover this method, or the door's grant does not name this app	object
`429`	Too many requests: this key has spent its request ceiling, and `Retry-After` says when to come back	object
`500`	This app failed while answering	object
`503`	A service this app needs did not answer — the door could not be reached, so this request was not checked	object

Example

Count the direct children of one or more folders, with a token from the door.

POST /_/api/v1/counts

curl -X POST 'https://zpe.vc/files/_/api/v1/counts' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

200 application/json

{}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

DELETE /_/api/v1/delete Delete a file or folder, or move it to the trash with `?soft=1` deleteDelete

Delete a file or folder, or move it to the trash with `?soft=1`

Parameters

name	in	required	type	notes
`path`	query	yes	string	The file or folder to delete, relative to the account's prefix.
`soft`	query	no	boolean	Move it to the trash instead of deleting it.

Request body

None: this operation takes its arguments in the path and the query.

Responses

status	meaning	body
`200`	It is gone, or — with `soft` — it moved to the trash and this is the `trashKey` a restore takes.	object
`400`	`path` is missing or is not a usable key, or names the internal prefix.	object
`401`	The credential is missing or does not open this account	object
`403`	This account may not do that: the key's scope does not cover this method, or the door's grant does not name this app	object
`404`	`path` names nothing in this account's prefix.	object
`429`	Too many requests: this key has spent its request ceiling, and `Retry-After` says when to come back	object
`500`	This app failed while answering	object
`503`	A service this app needs did not answer — the door could not be reached, so this request was not checked	object

Example

Delete a file or folder, or move it to the trash with `?soft=1`, with a token from the door.

DELETE /_/api/v1/delete

curl -X DELETE 'https://zpe.vc/files/_/api/v1/delete?path=string&soft=false' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

200 application/json

{}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

GET /_/api/v1/download Download one file's bytes getDownload

Download one file's bytes

Parameters

name	in	required	type	notes
`path`	query	yes	string	The object key to read, relative to the account's prefix.

Request body

None: this operation takes its arguments in the path and the query.

Responses

status	meaning	body
`200`	The file's bytes, with its type, length and `ETag`.	object
`206`	Part of the file's bytes, when the request carried a `Range` header.	object
`400`	`path` is missing or is not a usable key, or names a folder: a folder has no bytes to send.	object
`401`	The credential is missing or does not open this account	object
`403`	This account may not do that: the key's scope does not cover this method, or the door's grant does not name this app	object
`404`	`path` names nothing in this account's prefix.	object
`429`	Too many requests: this key has spent its request ceiling, and `Retry-After` says when to come back	object
`500`	This app failed while answering	object
`503`	A service this app needs did not answer — the door could not be reached, so this request was not checked	object

Example

Download one file's bytes, with a token from the door.

GET /_/api/v1/download

curl -X GET 'https://zpe.vc/files/_/api/v1/download?path=string' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

200 application/json

{}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

GET /_/api/v1/list List one folder, sorted, folders first getList

List one folder, sorted, folders first

Parameters

name	in	required	type	notes
`cursor`	query	no	string	The `nextCursor` a previous page answered, to read the next one.
`limit`	query	no	integer	How many entries to answer. The whole folder when absent.
`path`	query	no	string	The folder to list, relative to the account's prefix. The root when absent.

Request body

None: this operation takes its arguments in the path and the query.

Responses

status	meaning	body
`200`	The folder's entries, folders first, and a `nextCursor` when there is another page.	object
`400`	`path` is not a usable key, names a file rather than a folder, or `limit` is outside 1-1000.	object
`401`	The credential is missing or does not open this account	object
`403`	This account may not do that: the key's scope does not cover this method, or the door's grant does not name this app	object
`404`	`path` names no folder in this account's prefix.	object
`429`	Too many requests: this key has spent its request ceiling, and `Retry-After` says when to come back	object
`500`	This app failed while answering	object
`503`	A service this app needs did not answer — the door could not be reached, so this request was not checked	object

Example

List one folder, sorted, folders first, with a token from the door.

GET /_/api/v1/list

curl -X GET 'https://zpe.vc/files/_/api/v1/list?cursor=string&limit=0&path=string' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

200 application/json

{}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

POST /_/api/v1/mkdir Create a folder, with its parent markers postMkdir

Create a folder, with its parent markers

Parameters

name	in	required	type	notes
`Idempotency-Key`	header	no	string	A value that names this attempt. Send the same one when retrying and the answer is what the first call wrote (`200`) instead of a second object; present and empty is refused.
`path`	query	yes	string	The folder to create, relative to the account's prefix.

Request body

None: this operation takes its arguments in the path and the query.

Responses

status	meaning	body
`200`	Nothing new was written: this `Idempotency-Key` already created that folder, or the folder was already there. `created` is `false` and `existed` says what was found.	object
`201`	The folder was created, with its parent markers.	object
`400`	The request could not be read	object
`401`	The credential is missing or does not open this account	object
`403`	This account may not do that	object
`404`	Nothing is here	object
`409`	A file of that name is already there, so a folder cannot take the address.	object
`429`	Too many requests	object

Example

Create a folder, with its parent markers, with a token from the door.

POST /_/api/v1/mkdir

curl -X POST 'https://zpe.vc/files/_/api/v1/mkdir?path=string' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

200 application/json

{
  "key": "string",
  "created": false,
  "existed": "directory"
}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

POST /_/api/v1/rename Rename or move a file or folder postRename

Rename or move a file or folder

Parameters

name	in	required	type	notes
`from`	query	no	string	The file or folder to move. Send it here or as `from` in a JSON body.
`overwrite`	query	no	boolean	Replace the destination when it already exists. Default false.
`to`	query	no	string	Its new path. Send it here or as `to` in a JSON body.

Request body

None: this operation takes its arguments in the path and the query.

Responses

status	meaning	body
`200`	It moved, and `from` no longer exists.	object
`400`	`from` or `to` is missing or is not a usable key, is the same as the other or sits inside it, names the internal prefix, or `overwrite` was asked for on a folder move; or the JSON body could not be read.	object
`401`	The credential is missing or does not open this account	object
`403`	This account may not do that: the key's scope does not cover this method, or the door's grant does not name this app	object
`404`	`from` names nothing in this account's prefix.	object
`409`	`to` is already there, and either `overwrite` was not asked for or the destination is a folder.	object
`429`	Too many requests: this key has spent its request ceiling, and `Retry-After` says when to come back	object
`500`	This app failed while answering	object
`503`	A service this app needs did not answer — the door could not be reached, so this request was not checked	object

Example

Rename or move a file or folder, with a token from the door.

POST /_/api/v1/rename

curl -X POST 'https://zpe.vc/files/_/api/v1/rename?from=string&overwrite=false&to=string' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

200 application/json

{}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

GET /_/api/v1/search Search the account's files by name getSearch

Search the account's files by name

Parameters

name	in	required	type	notes
`cursor`	query	no	string	The `nextCursor` a previous page answered, to read the next one.
`limit`	query	no	integer	How many hits to answer. Default 100.
`match`	query	no	"name"	`name` matches a file's whole name instead of a substring of it, for a caller that knows the name it wants.
`prefix`	query	no	string	Only search under this folder, relative to the account's prefix.
`q`	query	no	string	The text to find in a file's name. An empty one answers nothing rather than everything.

Request body

None: this operation takes its arguments in the path and the query.

Responses

status	meaning	body
`200`	The names that matched, and a `nextCursor` when the scan stopped with more to read. An empty `q` answers an empty page rather than every file.	object
`401`	The credential is missing or does not open this account	object
`403`	This account may not do that: the key's scope does not cover this method, or the door's grant does not name this app	object
`429`	Too many requests: this key has spent its request ceiling, and `Retry-After` says when to come back	object
`500`	This app failed while answering	object
`503`	A service this app needs did not answer — the door could not be reached, so this request was not checked	object

Example

Search the account's files by name, with a token from the door.

GET /_/api/v1/search

curl -X GET 'https://zpe.vc/files/_/api/v1/search?cursor=string&limit=0&match=name&prefix=string&q=string' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

200 application/json

{}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

GET /_/api/v1/stat Read one file's metadata without its bytes getStat

Read one file's metadata without its bytes

Parameters

name	in	required	type	notes
`path`	query	yes	string	The object key to read the metadata of, relative to the account's prefix.

Request body

None: this operation takes its arguments in the path and the query.

Responses

status	meaning	body
`200`	One file's or folder's metadata, without its bytes. A folder answers `kind: directory`.	object
`400`	`path` is missing or is not a usable key, or names the internal prefix.	object
`401`	The credential is missing or does not open this account	object
`403`	This account may not do that: the key's scope does not cover this method, or the door's grant does not name this app	object
`404`	`path` names nothing in this account's prefix.	object
`429`	Too many requests: this key has spent its request ceiling, and `Retry-After` says when to come back	object
`500`	This app failed while answering	object
`503`	A service this app needs did not answer — the door could not be reached, so this request was not checked	object

Example

Read one file's metadata without its bytes, with a token from the door.

GET /_/api/v1/stat

curl -X GET 'https://zpe.vc/files/_/api/v1/stat?path=string' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

200 application/json

{}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

GET /_/api/v1/trash List the trash, restore from it, or empty it getTrash

List the trash, restore from it, or empty it

Parameters

No parameters.

Request body

None: this operation takes its arguments in the path and the query.

Responses

status	meaning	body
`200`	Everything in the trash, including entries whose retention has just run out and been purged.	object
`401`	The credential is missing or does not open this account	object
`403`	This account may not do that: the key's scope does not cover this method, or the door's grant does not name this app	object
`429`	Too many requests: this key has spent its request ceiling, and `Retry-After` says when to come back	object
`500`	This app failed while answering	object
`503`	A service this app needs did not answer — the door could not be reached, so this request was not checked	object

Example

List the trash, restore from it, or empty it, with a token from the door.

GET /_/api/v1/trash

curl -X GET 'https://zpe.vc/files/_/api/v1/trash' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

200 application/json

{}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

POST /_/api/v1/trash List the trash, restore from it, or empty it postTrash

List the trash, restore from it, or empty it

Parameters

name	in	required	type	notes
`action`	query	no	"restore"	`restore` restores the keys named in the body. Absent, the body's keys are soft-deleted instead.

Request body

None: this operation takes its arguments in the path and the query.

Responses

status	meaning	body
`200`	`action=restore` answers one result per `trashKey` — restored, or why it could not be. Without it, the body's `keys` moved to the trash and this is each one's id.	object
`400`	The JSON body could not be read, or — without `action=restore` — carried no `keys` to move.	object
`401`	The credential is missing or does not open this account	object
`403`	This account may not do that: the key's scope does not cover this method, or the door's grant does not name this app	object
`429`	Too many requests: this key has spent its request ceiling, and `Retry-After` says when to come back	object
`500`	This app failed while answering	object
`503`	A service this app needs did not answer — the door could not be reached, so this request was not checked	object

Example

List the trash, restore from it, or empty it, with a token from the door.

POST /_/api/v1/trash

curl -X POST 'https://zpe.vc/files/_/api/v1/trash?action=restore' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

200 application/json

{}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

DELETE /_/api/v1/trash List the trash, restore from it, or empty it deleteTrash

List the trash, restore from it, or empty it

Parameters

No parameters.

Request body

None: this operation takes its arguments in the path and the query.

Responses

status	meaning	body
`204`	The named `trashKeys` — or everything, with `all` — were removed from the trash and their bytes with them. Nothing to send back.
`400`	The JSON body could not be read, so there were no entries to remove.	object
`401`	The credential is missing or does not open this account	object
`403`	This account may not do that: the key's scope does not cover this method, or the door's grant does not name this app	object
`429`	Too many requests: this key has spent its request ceiling, and `Retry-After` says when to come back	object
`500`	This app failed while answering	object
`503`	A service this app needs did not answer — the door could not be reached, so this request was not checked	object

Example

List the trash, restore from it, or empty it, with a token from the door.

DELETE /_/api/v1/trash

curl -X DELETE 'https://zpe.vc/files/_/api/v1/trash' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

POST /_/api/v1/upload Upload a file, or write and remove one raw PUT at a time postUpload

Upload a file, or write and remove one raw PUT at a time

Parameters

name	in	required	type	notes
`Idempotency-Key`	header	no	string	A value that names this attempt. Send the same one when retrying and the answer is what the first call wrote (`200`) instead of a second object; present and empty is refused.
`overwrite`	query	no	boolean	Replace a file of the same name. Default false.
`path`	query	no	string	The folder to write into — or, with `uploads`, the file key the multipart upload is for.
`uploadId`	query	no	string	Complete the multipart upload this id names, with the parts in a JSON body.
`uploads`	query	no	boolean	Start a multipart upload and answer its `uploadId`. Send it with no value.

Request body

None: this operation takes its arguments in the path and the query.

Responses

status	meaning	body
`200`	Nothing new was written: this `Idempotency-Key` already answered here, and this is what the first call wrote — the same key, name, size and `uploadId`.	object
`201`	The file was written, or — with `uploads` — a multipart upload was started and this is its `uploadId`.	object
`400`	The request could not be read	object
`401`	The credential is missing or does not open this account	object
`403`	This account may not do that	object
`404`	Nothing is here	object
`409`	The destination is a folder, so it cannot be replaced by this file.	object
`413`	The body is larger than this deployment accepts in one request.	object
`429`	Too many requests	object

Example

Upload a file, or write and remove one raw PUT at a time, with a token from the door.

POST /_/api/v1/upload

curl -X POST 'https://zpe.vc/files/_/api/v1/upload?overwrite=false&path=string&uploadId=string&uploads=false' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

200 application/json

{
  "key": "string",
  "name": "string",
  "size": 0,
  "path": "string",
  "overwritten": false,
  "uploadId": "string"
}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

PUT /_/api/v1/upload Upload a file, or write and remove one raw PUT at a time putUpload

Upload a file, or write and remove one raw PUT at a time

Parameters

name	in	required	type	notes
`partNumber`	query	yes	integer	Which part this body is, counted from 1.
`path`	query	yes	string	The file key this part belongs to.
`uploadId`	query	yes	string	The multipart upload this part belongs to.

Request body

None: this operation takes its arguments in the path and the query.

Responses

status	meaning	body
`200`	The part was written, and this is its `partNumber` and `ETag` for the completing call.	object
`400`	`path`, `uploadId` or `partNumber` is missing or is not usable, the request carried no body, or the upload refused the part.	object
`401`	The credential is missing or does not open this account	object
`403`	This account may not do that: the key's scope does not cover this method, or the door's grant does not name this app	object
`429`	Too many requests: this key has spent its request ceiling, and `Retry-After` says when to come back	object
`500`	This app failed while answering	object
`503`	A service this app needs did not answer — the door could not be reached, so this request was not checked	object

Example

Upload a file, or write and remove one raw PUT at a time, with a token from the door.

PUT /_/api/v1/upload

curl -X PUT 'https://zpe.vc/files/_/api/v1/upload?partNumber=0&path=string&uploadId=string' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

200 application/json

{}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

DELETE /_/api/v1/upload Upload a file, or write and remove one raw PUT at a time deleteUpload

Upload a file, or write and remove one raw PUT at a time

Parameters

name	in	required	type	notes
`path`	query	yes	string	The file key the abandoned upload was for.
`uploadId`	query	yes	string	The multipart upload to abandon.

Request body

None: this operation takes its arguments in the path and the query.

Responses

status	meaning	body
`204`	The multipart upload was abandoned and its parts are gone. An `uploadId` that was never live is treated as already abandoned, so this answer is idempotent.
`400`	`path` or `uploadId` is missing or is not a usable key.	object
`401`	The credential is missing or does not open this account	object
`403`	This account may not do that: the key's scope does not cover this method, or the door's grant does not name this app	object
`429`	Too many requests: this key has spent its request ceiling, and `Retry-After` says when to come back	object
`500`	This app failed while answering	object
`503`	A service this app needs did not answer — the door could not be reached, so this request was not checked	object

Example

Upload a file, or write and remove one raw PUT at a time, with a token from the door.

DELETE /_/api/v1/upload

curl -X DELETE 'https://zpe.vc/files/_/api/v1/upload?path=string&uploadId=string' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

Matches in other apps

zpe files

Parameters

Request body

Responses

Example

Parameters

Request body

Responses

Example

Parameters

Request body

Responses

Example

Parameters

Request body

Responses

Example

Parameters

Request body

Responses

Example

Parameters

Request body

Responses

Example

Parameters

Request body

Responses

Example

Parameters

Request body

Responses

Example

Parameters

Request body

Responses

Example

Parameters

Request body

Responses

Example

Parameters

Request body

Responses

Example

Parameters

Request body

Responses

Example

Parameters

Request body

Responses

Example

Parameters

Request body

Responses

Example

Parameters

Request body

Responses

Example