%PDF-
%PDF-
Mini Shell
Mini Shell
openapi: 3.0.0
info:
description: "Access token should be sent along with every request to SITE_NAME API in authorization header: `Authorization: Bearer <Token>` <br> This token can either be acquired via `auth/login` endpoint or from account settings page on [SITE_NAME website](SITE_URL/account/settings)."
version: "1.0.0"
title: SITE_NAME API
security:
- accessToken: [ ]
tags:
- name: Uploads
description: Upload files to SITE_NAME
- name: Chunked Uploads
description: Upload files using chunked uploading
- name: Auth
description: Authenticate requests to the API
- name: Files and Folders
description: FileEntry refers to either a file or folder on SITE_NAME
- name: Sharing
description: Manage file entry collaborators
- name: Starring
description: Mark or unmark entries as starred
- name: Shareable Links
description: Manage shareable links for file or folder
paths:
/uploads:
post:
tags:
- Uploads
summary: Upload a file to SITE_NAME
operationId: upload
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
file:
type: string
format: binary
description: Content of file to upload to SITE_NAME
parentId:
type: integer
description: ID of folder where this file should be uploaded, `null` will upload to root
example: null
relativePath:
type: string
description: "Folders in the path provided here will be auto created, if they don't exist already. This is mainly useful when uploading a folder from browser. It should include original filename as well: <br> `/some/folders/here/file-name.jpg`"
responses:
'201':
description: File was uploaded
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: success
fileEntry:
$ref: '#/components/schemas/FileEntry'
'401':
$ref: '#/components/schemas/401-Response'
'403':
$ref: '#/components/schemas/403-Response'
'422':
description: Invalid data specified
content:
application/json:
schema:
$ref: '#/components/schemas/422-Response'
/uploads/sessions/load:
post:
tags:
- Chunked Uploads
operationId: loadUploadSession
description: "This will either create a new upload session for specified `fingerprint`, or load an existing one if it was previously created.<br><br>All parameters for chunked uploading should be included via headers and prefixed with `Be-`"
parameters:
- in: header
name: "Be-Fingerprint"
required: true
schema:
type: string
description: Unique fingerprint for the file. Can be checksum of file content or serialized string from file name, content length and last modified date. This fingerprint will need to be sent to SITE_NAME when uploading each chunk.
- in: header
name: "Be-Chunk-Count"
required: true
schema:
type: integer
description: Total number of chunks for the file (file size / chunk size usually)
example: 15
- in: header
name: "Be-Original-Filename"
required: true
schema:
type: string
example: image.png
- in: header
name: "Be-Metadata"
schema:
type: string
description: "Additional metadata. Value should be base64 encoded"
example: "key1: value1, key2: value2, key3: value3"
responses:
'200':
description: Upload Session was created or existing one loaded. If file was already fully uploaded for this session `fileEntry` will be included and no further actions are required.
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: success
uploadedChunks:
type: array
items:
type: object
properties:
number:
type: integer
description: Number (index) of the chunk
size:
type: integer
description: Size of the chunk in bytes
fileEntry:
$ref: '#/components/schemas/FileEntry'
'401':
$ref: '#/components/schemas/401-Response'
'403':
$ref: '#/components/schemas/403-Response'
'422':
description: Invalid data specified
content:
application/json:
schema:
$ref: '#/components/schemas/422-Response'
/uploads/sessions/chunks:
post:
tags:
- Chunked Uploads
operationId: uploadChunk
description: "Uploads a sinle file chunk to SITE_NAME.<br><br>All parameters for chunked uploading should be included via headers and prefixed with `Be-`"
parameters:
- in: header
name: "Be-Fingerprint"
required: true
schema:
type: string
description: Unique fingerprint for the file. Can be checksum of file content or serialized string from file name, content length and last modified date. This fingerprint will need to be sent to SITE_NAME when uploading each chunk.
- in: header
name: "Be-Chunk-Count"
required: true
schema:
type: integer
description: Total number of chunks for the file (file size / chunk size usually)
example: 15
- in: header
name: "Be-Chunk-Index"
required: true
schema:
type: integer
description: Index of this chunk
example: 3
- in: header
name: "Be-Original-Filename"
required: true
schema:
type: string
example: image.png
- in: header
name: "Be-Metadata"
schema:
type: string
description: "Additional metadata. Value should be base64 encoded"
example: "key1: value1, key2: value2, key3: value3"
responses:
'200':
description: Chunk was uploaded. If all chunks have been uploaded already for this session `fileEntry` will be included and no further actions are required.
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: success
fileEntry:
$ref: '#/components/schemas/FileEntry'
'401':
$ref: '#/components/schemas/401-Response'
'403':
$ref: '#/components/schemas/403-Response'
'422':
description: Invalid data specified
content:
application/json:
schema:
$ref: '#/components/schemas/422-Response'
/entries:
get:
tags:
- Files and Folders
summary: Get file entries
description: Get the list of all file entries you have access to
operationId: indexEntry
parameters:
- name: perPage
in: query
description: How many entries to return per page
schema:
type: "integer"
format: "int64"
default: 50
- name: deletedOnly
in: query
description: Whether only trashed entries should be returned
schema:
type: "boolean"
- name: starredOnly
in: query
description: Whether only starred entries should be returned
schema:
type: "boolean"
- name: recentOnly
in: query
description: Whether only recent entries should be returned
schema:
type: "boolean"
- name: sharedOnly
in: query
description: Whether only entries that have been shared with you should be returned
schema:
type: "boolean"
- name: query
in: query
description: Search query entry names should be filtered on
schema:
type: "string"
- name: type
in: query
description: File type entries should be filtered on
schema:
type: "string"
enum:
- "folder"
- "image"
- "text"
- "audio"
- "video"
- "pdf"
- name: parentIds
in: query
description: Only entries that are children of specified folders will be returned
explode: false
schema:
type: array
items:
type: string
responses:
'200':
description: Successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/FileEntry'
'401':
$ref: '#/components/schemas/401-Response'
'403':
$ref: '#/components/schemas/403-Response'
put:
tags:
- Files and Folders
summary: Update an existing file entry
operationId: entryUpdate
responses:
'200':
description: Entry updated
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: success
fileEntry:
$ref: '#/components/schemas/FileEntry'
'401':
$ref: '#/components/schemas/401-Response'
'403':
$ref: '#/components/schemas/403-Response'
'422':
description: Invalid data specified
content:
application/json:
schema:
$ref: '#/components/schemas/422-Response'
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
example: 'New name for the entry'
description:
type: string
example: 'New description for the entry'
delete:
tags:
- Files and Folders
summary: Move entries to trash or delete permanently
operationId: entriesDelete
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
entryIds:
description: list of entry IDs to delete
type: array
items:
type: string
deleteForever:
description: Whether entries should be deleted permantently, instead of being moved to trash
type: string
example: false
responses:
'200':
description: Entries deleted successfully
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: success
'401':
$ref: '#/components/schemas/401-Response'
'403':
$ref: '#/components/schemas/403-Response'
'422':
description: Invalid data specified
content:
application/json:
schema:
$ref: '#/components/schemas/422-Response'
/folders:
post:
tags:
- Files and Folders
summary: Create a new folder
operationId: createFolder
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
example: "new folder name"
parentId:
type: integer
description: "ID of parent folder or null if it should be created at root"
example: null
responses:
'200':
description: Folder created
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: success
folder:
$ref: '#/components/schemas/FileEntry'
'401':
$ref: '#/components/schemas/401-Response'
'403':
$ref: '#/components/schemas/403-Response'
'422':
description: Invalid data specified
content:
application/json:
schema:
$ref: '#/components/schemas/422-Response'
/entries/move:
post:
tags:
- Files and Folders
summary: Movie specified entries to a different folder
operationId: entriesMove
responses:
'200':
description: File entries moved successfully
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: success
entries:
type: array
items:
$ref: '#/components/schemas/FileEntry'
'401':
$ref: '#/components/schemas/401-Response'
'403':
$ref: '#/components/schemas/403-Response'
'422':
description: Invalid data specified
content:
application/json:
schema:
$ref: '#/components/schemas/422-Response'
requestBody:
content:
application/json:
schema:
type: object
required:
- entryIds
properties:
entryIds:
description: List of entry ids
type: array
items:
type: integer
format: "int32"
destination:
type: integer
format: "int32"
description: ID of folder specified entries should be moved to
example: null
/entries/copy:
post:
tags:
- Files and Folders
summary: Copy specified entries to a folder
operationId: entriesCopy
responses:
'200':
description: File entries copied successfully
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: success
entries:
type: array
items:
$ref: '#/components/schemas/FileEntry'
'401':
$ref: '#/components/schemas/401-Response'
'403':
$ref: '#/components/schemas/403-Response'
'422':
description: Invalid data specified
content:
application/json:
schema:
$ref: '#/components/schemas/422-Response'
requestBody:
content:
application/json:
schema:
type: object
required:
- entryIds
properties:
entryIds:
description: List of entry ids
type: array
items:
type: integer
format: "int32"
destination:
type: integer
format: "int32"
description: ID of folder specified entries should be moved to
example: null
/entries/restore:
post:
tags:
- Files and Folders
summary: Restore file entries from trash to original folder
operationId: entriesRestore
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- entryIds
properties:
entryIds:
description: List of entry IDs
type: array
items:
type: integer
format: "int32"
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: success
'401':
$ref: '#/components/schemas/401-Response'
'403':
$ref: '#/components/schemas/403-Response'
'422':
description: Invalid data specified
content:
application/json:
schema:
$ref: '#/components/schemas/422-Response'
/entries/add-users:
post:
tags:
- Sharing
summary: Share file or folder with specified users
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
entryIds:
type: array
items:
type: integer
emails:
type: array
items:
type: string
example: example@gmail.com
permissions:
type: array
items:
type: string
example: edit
enum:
- view
- edit
- download
responses:
'200':
description: Shared file entry successfully
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: success
users:
type: array
items:
$ref: '#/components/schemas/User'
'401':
$ref: '#/components/schemas/401-Response'
'403':
$ref: '#/components/schemas/403-Response'
'422':
description: Invalid data specified
content:
application/json:
schema:
$ref: '#/components/schemas/422-Response'
/entries/update-user/{userId}:
put:
tags:
- Sharing
summary: Change permissions user has for shared entries
parameters:
- in: path
name: userId
schema:
type: integer
required: true
requestBody:
content:
application/json:
schema:
type: object
properties:
entryIds:
type: array
items:
type: integer
permissions:
type: array
items:
type: string
example: edit
enum:
- view
- edit
- download
responses:
'200':
description: Changed permissions successfully
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: success
users:
type: array
items:
$ref: '#/components/schemas/User'
'401':
$ref: '#/components/schemas/401-Response'
'403':
$ref: '#/components/schemas/403-Response'
'422':
description: Invalid data specified
content:
application/json:
schema:
$ref: '#/components/schemas/422-Response'
/entries/remove-user/{userId}:
delete:
tags:
- Sharing
summary: Unshare file or folder with specified user
parameters:
- in: path
name: userId
schema:
type: integer
example: 1
required: true
description: ID of the user with whom entries should be unshared
- in: query
name: entryIds
description: list of entry IDs to unshare with user
schema:
type: array
items:
type: string
example: 1
responses:
'200':
description: Unshared file entry successfully
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: success
users:
type: array
items:
$ref: '#/components/schemas/User'
'401':
$ref: '#/components/schemas/401-Response'
'403':
$ref: '#/components/schemas/403-Response'
'422':
description: Invalid data specified
content:
application/json:
schema:
$ref: '#/components/schemas/422-Response'
/entries/star:
post:
tags:
- Starring
summary: Mark specified entries as starred
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
entryIds:
type: array
items:
type: integer
responses:
'200':
description: Marked as starred successfully
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: success
tag:
$ref: '#/components/schemas/Tag'
'401':
$ref: '#/components/schemas/401-Response'
'403':
$ref: '#/components/schemas/403-Response'
'422':
description: Invalid data specified
content:
application/json:
schema:
$ref: '#/components/schemas/422-Response'
/entries/unstar:
post:
tags:
- Starring
summary: Unmark specified entries as starred
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
entryIds:
type: array
items:
type: integer
responses:
'200':
description: Unmarked as starred successfully
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: success
tag:
$ref: '#/components/schemas/Tag'
'401':
$ref: '#/components/schemas/401-Response'
'403':
$ref: '#/components/schemas/403-Response'
'422':
description: Invalid data specified
content:
application/json:
schema:
$ref: '#/components/schemas/422-Response'
/entries/{entryId}/shareable-link:
get:
tags:
- Shareable Links
summary: Retrieve shareable link for specified entry
operationId: getShareableLink
parameters:
- name: entryId
in: path
description: ID or hash of entry for which to get shareable link
required: true
schema:
type: integer
format: int64
minimum: 1
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/Shareable-Link-Response'
'401':
$ref: '#/components/schemas/401-Response'
'403':
$ref: '#/components/schemas/403-Response'
'404':
description: File entry or shareable link not found
'422':
description: Invalid data specified
content:
application/json:
schema:
$ref: '#/components/schemas/422-Response'
post:
tags:
- Shareable Links
summary: Create new shareable link for specified entry
operationId: createShareableLink
parameters:
- name: entryId
in: path
description: ID or hash of entry for which to get shareable link
required: true
schema:
type: integer
format: int64
minimum: 1
requestBody:
content:
application/json:
schema:
type: object
properties:
password:
type: string
example: "new password"
expires_at:
type: string
description: "2021-03-06T17:34:00.000000Z"
allow_edit:
type: boolean
example: false
allow_download:
type: boolean
example: false
responses:
'200':
description: Shareable link created
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: success
link:
$ref: '#/components/schemas/ShareableLink'
'401':
$ref: '#/components/schemas/401-Response'
'403':
$ref: '#/components/schemas/403-Response'
'422':
description: Invalid data specified
content:
application/json:
schema:
$ref: '#/components/schemas/422-Response'
/shareable-link/{linkId}:
put:
tags:
- Shareable Links
summary: Update shareable link details
operationId: updateShareableLink
parameters:
- name: linkId
in: path
description: ID of the link that needs to be deleted
required: true
schema:
type: integer
format: int64
minimum: 1
requestBody:
content:
application/json:
schema:
type: object
properties:
password:
type: string
example: "new password"
expires_at:
type: string
description: "2021-03-06T17:34:00.000000Z"
allow_edit:
type: boolean
example: false
allow_download:
type: boolean
example: false
responses:
'200':
description: Shareable link updated
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: success
link:
$ref: '#/components/schemas/ShareableLink'
'401':
$ref: '#/components/schemas/401-Response'
'403':
$ref: '#/components/schemas/403-Response'
'404':
description: Shareable link not found
'422':
description: Invalid data specified
content:
application/json:
schema:
$ref: '#/components/schemas/422-Response'
delete:
tags:
- Shareable Links
summary: Delete shareable link by ID
operationId: deleteShareableLink
parameters:
- name: linkId
in: path
description: ID of the link that needs to be deleted
required: true
schema:
type: integer
format: int64
minimum: 1
responses:
'200':
description: Shareable link deleted
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: success
'401':
$ref: '#/components/schemas/401-Response'
'403':
$ref: '#/components/schemas/403-Response'
'404':
description: Shareable link not found
'422':
description: Invalid data specified
content:
application/json:
schema:
$ref: '#/components/schemas/422-Response'
/auth/register:
post:
security:
[ ]
tags:
- Auth
summary: Register for a new account
operationId: register
responses:
'200':
description: User registered
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: success
user:
$ref: '#/components/schemas/User'
'401':
$ref: '#/components/schemas/401-Response'
'403':
$ref: '#/components/schemas/403-Response'
'422':
description: Invalid data specified
content:
application/json:
schema:
$ref: '#/components/schemas/422-Response'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
email:
type: string
example: 'example@gmail.com'
password:
type: string
example: 'password'
device_name:
type: string
example: 'iphone 12'
/auth/login:
post:
security:
[ ]
tags:
- Auth
summary: Get access token
description: "Logs in specified user and returns user object along with access token. <br><br> Access Token is a string that enables SITE_NAME to verify that a request belongs to an authorized session. This token should be sent along with every request to SITE_NAME API in a authorization header: `Authorization: Bearer <Token>`."
operationId: login
responses:
'200':
description: Operation successful
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: success
user:
$ref: '#/components/schemas/User'
'401':
$ref: '#/components/schemas/401-Response'
'403':
$ref: '#/components/schemas/403-Response'
'422':
description: Invalid data specified
content:
application/json:
schema:
$ref: '#/components/schemas/422-Response'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
email:
type: string
example: 'example@gmail.com'
password:
type: string
example: 'password'
device_name:
type: string
example: 'iphone 12'
components:
schemas:
FileEntry:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
example: image.png
file_name:
type: string
example: j6oWHDG1z613UqFHLZpE1Yrqngw0N8XLuGNLNWJV
description: actual file name for this entry on storage
file_size:
type: integer
format: int64
example: 111863
description: In bytes
parent_id:
type: integer
format: int64
example: 1
description: Parent folder ID
parent:
$ref: '#/components/schemas/FileEntry'
thumbnail:
type: string
example: thumbnail.png
description: Relative path to thumbnail image for the file (if it exists)
mime:
type: string
example: image/png
url:
type: string
example: secure/uploads/3260
description: relative url for previewing file or folder contents
hash:
type: string
example: MzI2MHxwYWRkaQ
type:
type: string
enum:
- "image"
- "folder"
- "text"
- "audio"
- "video"
- "pdf"
description:
type: string
example: Example description entered by user
deleted_at:
type: string
example: "2021-02-23T14:42:38.000000Z"
description: date entry was moved to trash (if it's in trash currently)
created_at:
type: string
example: "2021-02-23T14:42:38.000000Z"
description: date entry was uploaded
updated_at:
type: string
example: "2021-02-23T14:42:38.000000Z"
description: date entry was last modified (content, name or location changed)
path:
type: string
example: "3260/3261/3262"
description: full path of parent folder IDs for this entry up to root
users:
type: array
items:
type: object
properties:
id:
type: integer
format: int64
email:
type: string
example: "example@gmail.com"
User:
type: object
properties:
id:
type: integer
format: int64
access_token:
type: string
description: Access token that can be used to authenticate API requests for this user
display_name:
type: string
first_name:
type: string
last_name:
type: string
email:
type: string
created_at:
type: string
example: "2021-02-23T14:42:38.000000Z"
updated_at:
type: string
example: "2021-02-23T14:42:38.000000Z"
Tag:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
xml:
name: Tag
ShareableLink:
type: object
properties:
id:
type: integer
format: int64
hash:
type: string
example: 3h8N1nxZq7WtyRmXDIosFupSl9MCrD
description: ID for link that will be visible in url
password:
type: string
example: $2y$10$BI8kz6zFeB0CA0P425eMSe7KJcm8OKjWijHTQrRP.cjqRtynMq4Sy
description: Passwords are hashed, so this will not match the password that was entered in plain text
user_id:
type: integer
format: int64
description: ID of user that created this link
entry_id:
type: integer
format: int64
description: ID of file entry this link is attached to
entry:
$ref: '#/components/schemas/FileEntry'
expires_at:
type: string
example: "2021-03-06T17:34:00.000000Z"
allow_edit:
type: boolean
example: false
allow_download:
type: boolean
example: false
Shareable-Link-Response:
type: object
properties:
status:
type: string
example: success
link:
$ref: '#/components/schemas/ShareableLink'
folderChildren:
description: If link is for folder, this will list immediate children of that folder
type: array
items:
$ref: '#/components/schemas/FileEntry'
errors:
type: object
properties:
some_data_1:
type: string
example: Error message for data 1
some_data_2:
type: string
example: Error message for data 2
401-Response:
description: Unauthenticated. Either access token is not provided or is invalid.
403-Response:
description: Unauthorized access. You don't have permissions required to perform this operation.
422-Response:
type: object
properties:
status:
type: string
example: error
message:
type: string
example: 'Reason for the error'
errors:
type: object
properties:
some_data_1:
type: string
example: Error message for data 1
some_data_2:
type: string
example: Error message for data 2
securitySchemes:
accessToken:
type: http
scheme: bearer
Zerion Mini Shell 1.0