Skip to content

Instantly share code, notes, and snippets.

@printminion

printminion/hidrive_openapi_v2.1-unofficial.yaml

Created November 11, 2019 17:12
Show Gist options
  • Save printminion/e0b7e2799ef15d87e1eb0c09cf1f34cf to your computer and use it in GitHub Desktop.
Save printminion/e0b7e2799ef15d87e1eb0c09cf1f34cf to your computer and use it in GitHub Desktop.
Download ZIP
hidrive_openapi_v2.1-unofficial.yaml
Raw
hidrive_openapi_v2.1-unofficial.yaml
openapi: 3.0.1
info:
title: hidrive API
description: API description in Markdown. https://api.hidrive.strato.com/2.1/static/apidoc/api.json
version: 2.1.0
externalDocs:
url: "https://dev.strato.com/hidrive/documentation"
servers:
- url: 'https://api.hidrive.strato.com/2.1'
description: Main (production) server
- url: http://staging-api.example.com
description: Optional server description, e.g. Internal staging server for testing
paths:
/user/me:
get:
tags:
- "user"
summary: Get data of authenticated User.
description: Optional extended description in Markdown.
operationId: "getUserMe"
security:
- BearerAuth: []
- oAuth2:
- owner,ro
- user,rw
- owner,rw
- admin,rw
- admin,ro
- user,ro
parameters:
- in: query
name: fields
required: false
example: 'account,alias,descr,email,email_pending,email_verified,encrypted,home,home_id,is_admin,is_owner,language,protocols,has_password'
schema:
type: string
description: Comma-separated list of response fields
- in: query
name: test
required: false
description: "WIP test for selectable items"
schema:
type: array
items:
type: string
enum:
- custom
- system
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/User'
example:
$ref: http://foo.bar#/examples/UserMe.json
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Not authenticated (no authentication)
'403':
description: 'Forbidden (Forbidden: Insufficient privileges)'
'500':
description: Internal Error
/app/me:
get:
description: 'This endpoint is intended to be used by applications to request
app-related information, for example the validity of their current ##refresh_token##
or their granted ##scope##.'
parameters:
- description: 'A comma-separated list of value types, that will be included
in the response. The performance of the call might be influenced by the
amount of information requested. Therefore, it is recommended to use a "need
to know" approach instead of "get all".
**The default is:**
##id,name,homepage,developer,developer.name
##
**Valid field names are:**
##created - timestamp - time of app registration
developer.email - email - developer contact email
developer.name - string - developer name
homepage - string - app homepage
id - int - id of the app
may_publish - bool - flag of publication permission
(*)
name - string - app name
private_folder - string - path to app folder (*)
private_folder_id - string - path identifier of app folder
(*)
publication_url - string - url of publication (*)
refresh_token.expires - timestamp - time of refresh_token expiry
refresh_token.expires_in - int - time TO refresh_token expiry
refresh_token.instance_id - string - refresh_token identifier
refresh_token.scope - string - granted scope of refresh_token
status - string - app status
##
Values marked with (*) are related to an experimental feature not available
by default to third party applications.
c&p friendly:
##created,developer.email,developer.name,homepage,id,may_publish,name,private_folder,private_folder_id,publication_url,refresh_token.expires,refresh_token.expires_in,refresh_token.instance_id,refresh_token.scope,status
##
Make sure to submit as CSV without spaces (use "(-ws)" in Method Playground)'
in: query
name: fields
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request
'401':
description: Unauthorized
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: 'This endpoint is intended to be used by applications to request app-related
information, for example the validity of their current ##refresh_token## or
their granted ##scope##'
tags:
- app
/changelog:
get:
description: 'This function returns the changelog data.
The "changelog" contains HiDrive related informative and commercial texts
in several languages. Some entries are also related to a specific HiDrive
tariff and are only available with authentication data.'
parameters:
- description: 'Language of the changelog entry represented by ISO_639-1 codes.
The currently supported languages are: ##de, en, es, fr, nl, pt##
You can also check available languages with: [L[/#cv#/changelog/languages_GET]GET
/#cv#/changelog/languages], but only use one language at a time.
If parameter is omitted, entries in all languages will be used.'
in: query
name: lang
required: false
schema:
type: string
- description: The number (positive integer) of entries to return. (counting
from latest entry)
in: query
name: max
required: false
schema:
type: number
- description: 'Unix timestamp. When set, only entries ##t_create > timestamp##
are returned.'
in: query
name: since
required: false
schema:
$ref: '#/components/schemas/Timestamp'
- description: 'Unix timestamp. When set, only entries ##t_create < timestamp##
are returned.'
in: query
name: until
required: false
schema:
$ref: '#/components/schemas/Timestamp'
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request
'404':
description: Not Found
'500':
description: Internal Error
security: []
summary: This function returns the changelog data
tags:
- changelog
/changelog/count:
get:
description: 'This function returns information about the amount of changelog
entries and can be filtered using the ##since## parameter.'
parameters:
- description: 'Unix timestamp. When set, only entries ##t_create > timestamp##
are returned.'
in: query
name: since
required: false
schema:
$ref: '#/components/schemas/Timestamp'
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request
'500':
description: Internal Error
security: []
summary: 'This function returns information about the amount of changelog entries
and can be filtered using the ##since## parameter'
tags:
- changelog
/changelog/languages:
get:
description: 'Returns a list of languages currently available for the changelog
represented by ISO_639-1 codes.
Those codes can be used as ##lang## parameter values in other ##/#cv#/changelog##
calls.'
parameters: []
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'500':
description: Internal Error
security: []
summary: Returns a list of languages currently available for the changelog represented
by ISO_639-1 codes
tags:
- changelog
/changelog/latest:
get:
description: 'Use this to get the timestamp of the latest changelog entry of
the given ##lang##. If no ##lang## parameter is given the latest overall entry
timestamp with language will be returned.
You may want to use this to check with some sort of local cache to determine
if you''ll need to update the displayed changelog.'
parameters:
- description: 'Language of the changelog entry represented by ISO_639-1 codes.
The currently supported languages are: ##de, en, es, fr, nl, pt##
You can also check available languages with: [L[/#cv#/changelog/languages_GET]GET
/#cv#/changelog/languages], but only use one language at a time.
If parameter is omitted, entries in all languages will be used.'
in: query
name: lang
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request
'404':
description: Not Found
'500':
description: Internal Error
security: []
summary: 'Use this to get the timestamp of the latest changelog entry of the
given ##lang##'
tags:
- changelog
/dir:
delete:
description: 'Delete a given directory. The optional parameter ##recursive##
determines, whether the operation shall fail on non-empty directories (which
is also the default behavior), or continue deleting recursively all contents.
Both, the ##pid## and ##path## parameters identify a filesystem object, at
least one of them is always mandatory.
It is allowed to use both together, in which case ##pid## addresses a superior
directory, and the value of ##path## is considered relative to that directory.
(##<pid>/<path>##)
Enforce the HiDrive ACLs but adjusts deviant POSIX ACLs of the src and his
parent when required. This may be necessary if the Permissions have been changed
using protocols like SMB or rsync. The permissions will be restored if the
operation completes successfully. Due to missing transactional semantics the
permissions may not be restored if the operation fails (e.g. with an exception)'
parameters:
- description: 'The path to a filesystem object.
Example: ##/users/example/Music##
The shortest possible path is ##"/"##, which will always refer to the topmost
directory accessible by the authenticated user. For a regular HiDrive user
this is the HiDrive ##"root"##. If used with a [L[/#cv#/share/token_POST]share
access_token] it will be the shared directory.
Note: if used in combination with a ##pid##, this value is not allowed to
start with ##"/"##.'
in: query
name: path
required: false
schema:
type: string
- description: 'The "PathID" is a path and encoding independant representation
of a specific filesystem object. Also returned and refered to as ##id##
in data related responses.
Example: ##d1372678008.d116##
Note: the ##pid## is not persistent upon changes (rename/move) to a filesystem
object.'
in: query
name: pid
required: false
schema:
type: string
- description: 'If set, the call will also delete non-empty directories and
their contents recursively without throwing a ##409 Conflict## error.'
in: query
name: recursive
required: false
schema:
type: boolean
- description: The modification time (mtime) of the file system target's parent
folder to be set after the operation.
in: query
name: parent_mtime
required: false
schema:
type: number
responses:
'204':
description: No Content
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'409':
description: Conflict
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Delete a given directory
tags:
- dir
get:
description: 'This is one of the main HiDrive data interaction endpoints. It
allows to query information about a given directory and all its contents.
**In short; A few things to be aware of:**
- ##path## and ##name## values are retuned as URL-encoded strings
- entries are returned in no particular order
- an implicit ##limit## of 5000 is imposed
- this also works for snapshots
**Usage details:**
Both, the ##pid## and ##path## parameters identify a filesystem object, at
least one of them is always mandatory.
It is allowed to use both together, in which case ##pid## addresses a superior
directory, and the value of ##path## is considered relative to that directory.
(##<pid>/<path>##)
To get the contents of a snapshot, use the ##path## parameter and the name
of a snapshot in the ##snapshot## parameter. The name must be UTF-8 encoded.
Available snapshot-names can be requested via [L[/#cv#/snapshot_GET]GET /#cv#/snapshot].
It is also possible to reference objects in snapshots by their ##pid##, however,
in this case the ##snapshot## parameter is neither needed nor allowed.
The parameters ##fields##, ##members## and ##limit## can be used to customize
the response.'
parameters:
- description: 'The path to a filesystem object.
Example: ##/users/example/Music##
The shortest possible path is ##"/"##, which will always refer to the topmost
directory accessible by the authenticated user. For a regular HiDrive user
this is the HiDrive ##"root"##. If used with a [L[/#cv#/share/token_POST]share
access_token] it will be the shared directory.
Note: if used in combination with a ##pid##, this value is not allowed to
start with ##"/"##.'
in: query
name: path
required: false
schema:
type: string
- description: 'The "PathID" is a path and encoding independant representation
of a specific filesystem object. Also returned and refered to as ##id##
in data related responses.
Example: ##d1372678008.d116##
Note: the ##pid## is not persistent upon changes (rename/move) to a filesystem
object.'
in: query
name: pid
required: false
schema:
type: string
- description: 'Comma-separated list of directory content types to be included
in the ##members## part of the response.
**The default is:**
##all
##
**Valid values are:**
##all - include all contents
none - do not return any members
dir - include sub-directories (not in combination with none or all)
file - include files (not in combination with none or all)
symlink - include symlinks (not in combination with none or all)
##
The result will contain a list of contents under the ##members## key if:
- the ##fields## parameter includes the literal "members" or values, that
begin with "members."
- OR the ##fields## parameter is not part of the request, at all
The list will be empty if the directory contains no filesystem objects of
the requested type.'
in: query
name: members
required: false
schema:
type: string
- description: 'Limits the number of directory entries returned, starting from
an optional offset.
**The default is:**
##5000
##
**Valid values are:**
##<limit> - limit, starting at offset=0
<offset>,<limit> - limit, starting at offset=<offset>
##
Both, ##<limit>## and ##<offset>## need to be positive integer values.
Currently, there is an **implicit limit**. The response will contain no
more than 5000 entries, even if the requested value is higher.'
in: query
name: limit
required: false
schema:
type: string
- description: 'Name of an existing snapshot, as returned by [L[/#cv#/snapshot_GET]GET
/#cv#/snapshot].
If provided, the requested ##path## will be looked up inside the referenced
snapshot.'
in: query
name: snapshot
required: false
schema:
type: string
- description: 'A comma-separated list of value types, that will be included
in the response. The performance of the call might be influenced by the
amount of information requested. Therefore, it is recommended to use a "need
to know" approach instead of "get all".
**The default is:**
##path,members.name
##
**Valid field names are:**
##chash (*) - string - recursive hashvalue for the directory
ctime - timestamp - ctime of the object
has_dirs - bool - contains subdirs?
id - string - path id (pid) of the directory
members - array - include information on dir contents
members.chash (*) - string - recursive hashvalue for a contained directory
members.ctime - timestamp - ctime of contained objects
members.has_dirs - bool - does a contained dir contain subdirs?
members.id - string - path id (pid) of contained object
members.image.exif - object - selected exif data of contained images
members.image.height - int - height of contained images
members.image.width - int - width of contained images
members.mhash (*) - string - meta hash of contained objects
members.mime_type - string - MIME type of contained files
members.mohash (*) - string - meta only hash of contained objects
members.mtime - timestamp - mtime of contained objects
members.name - string - URL-Encoded name of contained objects
members.nmembers (*) - int - number of members of a contained directory
members.nhash (*) - string - name hash of contained objects
members.path - string - URL-Encoded path of contained objects
members.parent_id - string - path id (pid) of the members parent
members.readable - bool - read-permission for contained objects
members.rshare - array - sharing information (details below)
members.size (*) - int - recursive size of a contained directory
members.type - string - dir/file/symlink (see param "members")
members.writable - bool - write-permission for contained objects
mhash (*) - string - meta hash of the object
mohash (*) - string - meta only hash of the object
mtime - timestamp - mtime of the directory
name - string - URL-Encoded name of the directory
nhash (*) - string - name hash of the object
nmembers - int - number of members in the directory
parent_id - string - path id (pid) of the parent directory
path - string - URL-Encoded path of the directory
readable - bool - read-permission for the directory
rshare - object - sharing information (details below)
size (*) - int - recursive size of the directory
type - string - dir/file/symlink (see param "members")
writable - bool - write-permission for the directory
##
c&p friendly:
##chash,ctime,has_dirs,id,members,members.chash,members.ctime,members.has_dirs,members.id,members.image.exif,members.image.height,members.image.width,members.mhash,members.mime_type,members.mohash,members.mtime,members.name,members.nmembers,members.nhash,members.parent_id,members.path,members.readable,members.rshare,members.size,members.type,members.writable,mhash,mohash,mtime,name,nhash,nmembers,parent_id,path,readable,rshare,size,type,writable
##
**Note:** that fields marked with ##(*)## will not be returned for snapshot
requests.
**Note:** that not all of the available fields will be returned for all
types of content files (members)
**Note:** that ##nmembers## always returnes the total, unfiltered number
of subdirectories, symlinks and files. This means that ##nmembers## might
differ from the size of ##members##
**Hash Information**
In order to use our synchronization feature, you''ll need to check several
hashes e.g. for file data, meta data etc. Those hashes are represented by
the field values:
##chash, mhash, mohash, nhash, members.chash, members.mhash, members.mohash,
members.nhash
##
Further information on the complete sync system can be found at the dedicated
sync documentation part of our developer page.'
in: query
name: fields
required: false
schema:
type: string
- description: 'Determines the order of the members in the result. They can
be sorted by name, mtime, type, or size. The default sort order is ascending.
Prefix the sort criterion with a dash ''-'' for descending order. The first
criteria in the comma-separated list take precedence over the others.
At the moment names are sorted case insensitive according to the de_DE locale.
The size of a directory is the recursive sum of filesizes of all files it
contains. The size of a directory in a snapshot is sorted as 0 and not reported.
**The default is:**
##name
##
**Example:**
##type,-mtime,name
##
List the directories first, then files. For a given type newer entries precede
older ones. If type and mtime match sort by name in ascending order.'
in: query
name: sort
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: This is one of the main HiDrive data interaction endpoints
tags:
- dir
post:
description: 'This Endpoint creates a new directories.
Provide a ##path## and optional superior ##pid## to create a new directory.
Both, the ##pid## and ##path## parameters identify a filesystem object, at
least one of them is always mandatory.
It is allowed to use both together, in which case ##pid## addresses a superior
directory, and the value of ##path## is considered relative to that directory.
(##<pid>/<path>##)
Note: This will not create all missing parent directories - the parent directory
within ##path## has to exist!
**Example:**
If you wish to create a directory "foobar" within "/users/example/somedir"
(pid: d123.2482537), send either one of:
##path=/users/example/somedir/foobar
OR
path=foobar&pid=d123.2482537
##
'
parameters:
- description: 'The path to a filesystem object.
Example: ##/users/example/Music##
The shortest possible path is ##"/"##, which will always refer to the topmost
directory accessible by the authenticated user. For a regular HiDrive user
this is the HiDrive ##"root"##. If used with a [L[/#cv#/share/token_POST]share
access_token] it will be the shared directory.
Note: if used in combination with a ##pid##, this value is not allowed to
start with ##"/"##.'
in: query
name: path
required: true
schema:
type: string
- description: 'The "PathID" is a path and encoding independant representation
of a specific filesystem object. Also returned and refered to as ##id##
in data related responses.
Example: ##d1372678008.d116##
Note: the ##pid## is not persistent upon changes (rename/move) to a filesystem
object.'
in: query
name: pid
required: false
schema:
type: string
- description: 'Optional parameter to determine the API behavior in case of
a conflict with an existing filesystem object.
**Possible value:**
##"autoname" - Find another name if the destination already exists.
"overwrite" - (not for directories) Replace destination object with source.
##
Note: when source and destination are the same, the operation results in
an ##error 409##.'
in: query
name: on_exist
required: false
schema:
type: string
- description: The modification time (mtime) of the file system target to be
set after the operation.
in: query
name: mtime
required: false
schema:
type: number
- description: The modification time (mtime) of the file system target's parent
folder to be set after the operation.
in: query
name: parent_mtime
required: false
schema:
type: number
responses:
'201':
description: Created
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'409':
description: Conflict
'422':
description: Unprocessable Entity (e.g. name too long)
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: This Endpoint creates a new directories
tags:
- dir
/dir/copy:
post:
description: 'This endpoint allows to copy a directory.
The parameters ##src## and ##src_id## as well as ##dst## and ##dst_id## identify
the source and destination for the operation. At least one source identifier
and ##dst## are always mandatory.
It is allowed to use the related parameters together, in which case ##src_id##
and ##dst_id## each addresses a superior directory, and the values of ##src##
and ##dst## are considered relative to that directory. (e.g.##<src_id>/<src>##)
To copy data from a snapshot directory, use the ##src## parameter and the
name of a snapshot in the ##snapshot## parameter. The name must be UTF-8 encoded.
Available snapshot-names can be requested via [L[/#cv#/snapshot_GET]GET /#cv#/snapshot].
It is also possible to reference objects in snapshots by their ##pid## (provided
as ##src_id##), however, in this case the ##snapshot## parameter is neither
needed nor allowed.'
parameters:
- description: 'The path to the filesystem object, that shall be the source
for the operation.
Example: ##/users/example/something##
It is not allowed to use only ##"/"## as a source, since it is the parent
for all possible targets.
Note: if used in combination with a ##src_id##, this value is not allowed
to start with ##"/"## either.'
in: query
name: src
required: false
schema:
type: string
- description: 'The "PathID" (##pid##) of the source filesystem object. (Or,
if used in combination with ##src##, its superior directory.)
Example: ##d1372678008.d116##
Note: a ##pid## is not persistent upon changes (rename/move) to a filesystem
object. So after this operation, the ##src_id## may no longer be valid.
However the current value will be part of the returned information (as ##id##)
after a successful request.'
in: query
name: src_id
required: false
schema:
type: string
- description: 'The path to the filesystem object, that shall be the destination
for the operation.
Example: ##/users/example/archive/something##
Note: if used in combination with a ##dst_id##, this value is not allowed
to start with ##"/"##.'
in: query
name: dst
required: true
schema:
type: string
- description: 'If provided, this must always be the ##pid## of a superior directory
of the ##dst##.
Example: d1372678008.d117'
in: query
name: dst_id
required: false
schema:
type: string
- description: 'Optional parameter to determine the API behavior in case of
a conflict with an existing filesystem object.
**Possible value:**
##"autoname" - Find another name if the destination already exists.
"overwrite" - (not for directories) Replace destination object with source.
##
Note: when source and destination are the same, the operation results in
an ##error 409##.'
in: query
name: on_exist
required: false
schema:
type: string
- description: 'Name of an existing snapshot, as returned by [L[/#cv#/snapshot_GET]GET
/#cv#/snapshot].
If provided, the requested ##path## will be looked up inside the referenced
snapshot.'
in: query
name: snapshot
required: false
schema:
type: string
- description: The modification time (mtime) of the destination parent folder
to be set after the operation.
in: query
name: dst_parent_mtime
required: false
schema:
type: number
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'409':
description: Conflict
'422':
description: Unprocessable Entity (e.g. name too long)
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: This endpoint allows to copy a directory
tags:
- dir
/dir/home:
get:
description: 'This is basically a convenience shortcut for [L[/#cv#/dir_GET]GET
/#cv#/dir] It will always return information about the personal (home) directory
of the authenticated user.
All non target-related parameters and general usage are the same as with [L[/#cv#/dir_GET]GET
/#cv#/dir]. However, this endpoint cannot be used with a [L[/#cv#/share/token_POST]share
token].'
parameters:
- description: 'Comma-separated list of directory content types to be included
in the ##members## part of the response.
**The default is:**
##all
##
**Valid values are:**
##all - include all contents
none - do not return any members
dir - include sub-directories (not in combination with none or all)
file - include files (not in combination with none or all)
symlink - include symlinks (not in combination with none or all)
##
The result will contain a list of contents under the ##members## key if:
- the ##fields## parameter includes the literal "members" or values, that
begin with "members."
- OR the ##fields## parameter is not part of the request, at all
The list will be empty if the directory contains no filesystem objects of
the requested type.'
in: query
name: members
required: false
schema:
type: string
- description: 'Limits the number of directory entries returned, starting from
an optional offset.
**The default is:**
##5000
##
**Valid values are:**
##<limit> - limit, starting at offset=0
<offset>,<limit> - limit, starting at offset=<offset>
##
Both, ##<limit>## and ##<offset>## need to be positive integer values.
Currently, there is an **implicit limit**. The response will contain no
more than 5000 entries, even if the requested value is higher.'
in: query
name: limit
required: false
schema:
type: string
- description: 'Name of an existing snapshot, as returned by [L[/#cv#/snapshot_GET]GET
/#cv#/snapshot].
If provided, the requested ##path## will be looked up inside the referenced
snapshot.'
in: query
name: snapshot
required: false
schema:
type: string
- description: 'A comma-separated list of value types, that will be included
in the response. The performance of the call might be influenced by the
amount of information requested. Therefore, it is recommended to use a "need
to know" approach instead of "get all".
**The default is:**
##path,members.name
##
**Valid field names are:**
##chash (*) - string - recursive hashvalue for the directory
ctime - timestamp - ctime of the object
has_dirs - bool - contains subdirs?
id - string - path id (pid) of the directory
members - array - include information on dir contents
members.chash (*) - string - recursive hashvalue for a contained directory
members.ctime - timestamp - ctime of contained objects
members.has_dirs - bool - does a contained dir contain subdirs?
members.id - string - path id (pid) of contained object
members.image.exif - object - selected exif data of contained images
members.image.height - int - height of contained images
members.image.width - int - width of contained images
members.mhash (*) - string - meta hash of contained objects
members.mime_type - string - MIME type of contained files
members.mohash (*) - string - meta only hash of contained objects
members.mtime - timestamp - mtime of contained objects
members.name - string - URL-Encoded name of contained objects
members.nmembers (*) - int - number of members of a contained directory
members.nhash (*) - string - name hash of contained objects
members.path - string - URL-Encoded path of contained objects
members.parent_id - string - path id (pid) of the members parent
members.readable - bool - read-permission for contained objects
members.rshare - array - sharing information (details below)
members.size (*) - int - recursive size of a contained directory
members.type - string - dir/file/symlink (see param "members")
members.writable - bool - write-permission for contained objects
mhash (*) - string - meta hash of the object
mohash (*) - string - meta only hash of the object
mtime - timestamp - mtime of the directory
name - string - URL-Encoded name of the directory
nhash (*) - string - name hash of the object
nmembers - int - number of members in the directory
parent_id - string - path id (pid) of the parent directory
path - string - URL-Encoded path of the directory
readable - bool - read-permission for the directory
rshare - object - sharing information (details below)
size (*) - int - recursive size of the directory
type - string - dir/file/symlink (see param "members")
writable - bool - write-permission for the directory
##
c&p friendly:
##chash,ctime,has_dirs,id,members,members.chash,members.ctime,members.has_dirs,members.id,members.image.exif,members.image.height,members.image.width,members.mhash,members.mime_type,members.mohash,members.mtime,members.name,members.nmembers,members.nhash,members.parent_id,members.path,members.readable,members.rshare,members.size,members.type,members.writable,mhash,mohash,mtime,name,nhash,nmembers,parent_id,path,readable,rshare,size,type,writable
##
**Note:** that fields marked with ##(*)## will not be returned for snapshot
requests.
**Note:** that not all of the available fields will be returned for all
types of content files (members)
**Note:** that ##nmembers## always returnes the total, unfiltered number
of subdirectories, symlinks and files. This means that ##nmembers## might
differ from the size of ##members##'
in: query
name: fields
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: This is basically a convenience shortcut for [L[/#cv#/dir_GET]GET /#cv#/dir]
It will always return information about the personal (home) directory of the
authenticated user
tags:
- dir
/dir/move:
post:
description: 'This endpoint allows to move a directory.
The parameters ##src## and ##src_id## as well as ##dst## and ##dst_id## identify
the source and destination for the operation. At least one source identifier
and ##dst## are always mandatory.
It is allowed to use the related parameters together, in which case ##src_id##
and ##dst_id## each addresses a superior directory, and the values of ##src##
and ##dst## are considered relative to that directory. (e.g.##<src_id>/<src>##)
Note: it is not possible to move data from a snapshot, use [L[/#cv#/dir/copy_POST]POST
/#cv#/dir/copy] for backup restoring.
'
parameters:
- description: 'The path to the filesystem object, that shall be the source
for the operation.
Example: ##/users/example/something##
It is not allowed to use only ##"/"## as a source, since it is the parent
for all possible targets.
Note: if used in combination with a ##src_id##, this value is not allowed
to start with ##"/"## either.'
in: query
name: src
required: false
schema:
type: string
- description: 'The "PathID" (##pid##) of the source filesystem object. (Or,
if used in combination with ##src##, its superior directory.)
Example: ##d1372678008.d116##
Note: a ##pid## is not persistent upon changes (rename/move) to a filesystem
object. So after this operation, the ##src_id## may no longer be valid.
However the current value will be part of the returned information (as ##id##)
after a successful request.'
in: query
name: src_id
required: false
schema:
type: string
- description: 'The path to the filesystem object, that shall be the destination
for the operation.
Example: ##/users/example/archive/something##
Note: if used in combination with a ##dst_id##, this value is not allowed
to start with ##"/"##.'
in: query
name: dst
required: true
schema:
type: string
- description: 'If provided, this must always be the ##pid## of a superior directory
of the ##dst##.
Example: d1372678008.d117'
in: query
name: dst_id
required: false
schema:
type: string
- description: 'Optional parameter to determine the API behavior in case of
a conflict with an existing filesystem object.
**Possible value:**
##"autoname" - Find another name if the destination already exists.
"overwrite" - (not for directories) Replace destination object with source.
##
Note: when source and destination are the same, the operation results in
an ##error 409##.'
in: query
name: on_exist
required: false
schema:
type: string
- description: The modification time (mtime) of the source parent folder to
be set after the operation.
in: query
name: src_parent_mtime
required: false
schema:
type: number
- description: The modification time (mtime) of the destination parent folder
to be set after the operation.
in: query
name: dst_parent_mtime
required: false
schema:
type: number
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'409':
description: Conflict
'422':
description: Unprocessable Entity (e.g. name too long)
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: This endpoint allows to move a directory
tags:
- dir
/dir/rename:
post:
description: 'Rename a directory.
Both, the ##pid## and ##path## parameters identify a filesystem object, at
least one of them is always mandatory.
It is allowed to use both together, in which case ##pid## addresses a superior
directory, and the value of ##path## is considered relative to that directory.
(##<pid>/<path>##)'
parameters:
- description: 'The path to a filesystem object.
Example: ##/users/example/Music##
The shortest possible path is ##"/"##, which will always refer to the topmost
directory accessible by the authenticated user. For a regular HiDrive user
this is the HiDrive ##"root"##. If used with a [L[/#cv#/share/token_POST]share
access_token] it will be the shared directory.
Note: if used in combination with a ##pid##, this value is not allowed to
start with ##"/"##.'
in: query
name: path
required: false
schema:
type: string
- description: 'The "PathID" is a path and encoding independant representation
of a specific filesystem object. Also returned and refered to as ##id##
in data related responses.
Example: ##d1372678008.d116##
Note: the ##pid## is not persistent upon changes (rename/move) to a filesystem
object.'
in: query
name: pid
required: false
schema:
type: string
- description: The new name of the given directory.
in: query
name: name
required: true
schema:
type: string
- description: 'Optional parameter to determine the API behavior in case of
a conflict with an existing filesystem object.
**Possible value:**
##"autoname" - Find another name if the destination already exists.
"overwrite" - (not for directories) Replace destination object with source.
##
Note: when source and destination are the same, the operation results in
an ##error 409##.'
in: query
name: on_exist
required: false
schema:
type: string
- description: The modification time (mtime) of the file system target's parent
folder to be set after the operation.
in: query
name: parent_mtime
required: false
schema:
type: number
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'409':
description: Conflict
'422':
description: Unprocessable Entity (e.g. name too long)
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Rename a directory
tags:
- dir
/features:
get:
description: 'Return information on HiDrive features of the authenticated user''s
tariff.
The HiDrive functionality is differentiated by so-called "features". These
represent single aspects of functions, like the number of user accounts a
specific HiDrive can have.
Many of the values affect the behavior of the API by limiting access to secific
functionality or the range of valid parameter values. It is therefore recommended
to check feature information first and adjust request parameters (eg. ttl)
accordingly.'
parameters:
- description: 'A comma-separated list of value types, that will be included
in the response. The performance of the call might be influenced by the
amount of information requested. Therefore, it is recommended to use a "need
to know" approach instead of "get all".
**The default is:**
##accounts_max,admins_max,language,protocols,quota,ssl
##
**Valid field names are:**
##accounts_max - int - maximum number of accounts
admins_max - int - maximum number of admin-accounts
gallery - bool - gallery features enabled?
language - string - default language code
mailupload_enabled - bool - mailupload feature enabled?
mailupload_max - int - maximum number of mailuploads per account
promotion_key - string - customer specific string (*)
protocols - array - a list of available protocols
quota - int - the tariff storage space limit in byte
sharelink_downloads - int - max configurable downloads per sharelink
sharelink_edit - bool - PUT #cv#/sharelink usable?
sharelink_enabled - bool - sharelink feature enabled?
sharelink_max - int - maximum number of shares per account
sharelink_password - bool - sharelink password protection enabled?
sharelink_ttl - int - maximum configurable validity in seconds
share_tokens - int - maximum tokens issued for access to
a share
shareupload_edit - bool - PUT #cv#/shareupload usable?
shareupload_enabled - bool - shareupload feature enabled?
shareupload_max - int - maximum number of shareuploads per
account
shareupload_password - bool - shareupload password protection enabled?
shareupload_ttl - int - maximum configurable validity in seconds
shareupload_uploads - int - max configurable uploads per shareupload
share_edit - bool - PUT #cv#/share usable?
share_enabled - bool - share feature enabled?
share_password - bool - share password protection enabled?
share_ttl - int - maximum number of shares per account
snapshot_displaycount - int - the amount of shapshots accessible
snapshot_manual_max - int - the amount of manually creatable snapshots
snapshot_schedule_type - string - "basic/advanced" schedule setup options
snapshot_ttl - int - maximum snapshot storage time in seconds
ssl - bool - allow limiting accounts to ssl connections
encryption - bool - end-to-end encryption feature enabled?
##
Unset (unlimited) features are returned as **null** in the responses.
(*) - This string is used to identify the user for special HiDrive promotional
events.
c&p friendly:
##accounts_max,admins_max,gallery,language,mailupload_enabled,mailupload_max,promotion_key,protocols,quota,sharelink_downloads,sharelink_edit,sharelink_enabled,sharelink_max,sharelink_password,sharelink_ttl,shareupload_edit,shareupload_enabled,shareupload_max,shareupload_password,shareupload_ttl,shareupload_uploads,share_edit,share_enabled,share_password,share_ttl,snapshot_displaycount,snapshot_manual_max,snapshot_schedule_type,snapshot_ttl,ssl,encryption
##
Make sure to submit as CSV without spaces (use "(-ws)" in Method Playground)'
in: query
name: fields
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request
'401':
description: Unauthorized
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Return information on HiDrive features of the authenticated user's
tariff
tags:
- features
/file:
delete:
description: 'Delete a given file.
Both, the ##pid## and ##path## parameters identify a filesystem object, at
least one of them is always mandatory.
It is allowed to use both together, in which case ##pid## addresses a superior
directory, and the value of ##path## is considered relative to that directory.
(##<pid>/<path>##)
Enforce the HiDrive ACLs but adjusts deviant POSIX ACLs of the src and his
parent when required. This may be necessary if the Permissions have been changed
using protocols like SMB or rsync. The permissions will be restored if the
operation completes successfully. Due to missing transactional semantics the
permissions may not be restored if the operation fails (e.g. with an exception)'
parameters:
- description: 'The path to a filesystem object.
Example: ##/users/example/Music##
The shortest possible path is ##"/"##, which will always refer to the topmost
directory accessible by the authenticated user. For a regular HiDrive user
this is the HiDrive ##"root"##. If used with a [L[/#cv#/share/token_POST]share
access_token] it will be the shared directory.
Note: if used in combination with a ##pid##, this value is not allowed to
start with ##"/"##.'
in: query
name: path
required: false
schema:
type: string
- description: 'The "PathID" is a path and encoding independant representation
of a specific filesystem object. Also returned and refered to as ##id##
in data related responses.
Example: ##d1372678008.d116##
Note: the ##pid## is not persistent upon changes (rename/move) to a filesystem
object.'
in: query
name: pid
required: false
schema:
type: string
- description: The modification time (mtime) of the file system target's parent
folder to be set after the operation.
in: query
name: parent_mtime
required: false
schema:
type: number
responses:
'204':
description: No Content
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Delete a given file
tags:
- file
get:
description: 'This endpoint can be used to retrieve single files.
**Usage details:**
Both, the ##pid## and ##path## parameters identify a filesystem object, at
least one of them is always mandatory.
It is allowed to use both together, in which case ##pid## addresses a superior
directory, and the value of ##path## is considered relative to that directory.
(##<pid>/<path>##)
Serves the requested file as is. The response header ##Content-Type## is set
appropriately, if the file''s MIME type is known, otherwise it contains ##application/octet-stream##. This
mode supports HTTP/1.1 conditional requests with ##If-Modified-Since## (RFC
2616 Sec. 14.25) and range requests (RFC 2616 Sec. 14.35, only a single byte
range is supported).
To get the contents of a snapshot, use the ##path## parameter and the name
of a snapshot in the ##snapshot## parameter. The name must be UTF-8 encoded.
Available snapshot-names can be requested via [L[/#cv#/snapshot_GET]GET /#cv#/snapshot].
It is also possible to reference objects in snapshots by their ##pid##, however,
in this case the ##snapshot## parameter is neither needed nor allowed.
In some cases, it might be required to pass authentication-data via request
parameter instead of the "Authentication" header (if the environment does
not allow for header-data to be set, as in HTML img-tags). You can use ##access_token=BASE64_access_token##
for those situations. However, if "Authentication" header-data can be set,
it should be the preferred way.'
parameters:
- description: 'The path to a filesystem object.
Example: ##/users/example/Music##
The shortest possible path is ##"/"##, which will always refer to the topmost
directory accessible by the authenticated user. For a regular HiDrive user
this is the HiDrive ##"root"##. If used with a [L[/#cv#/share/token_POST]share
access_token] it will be the shared directory.
Note: if used in combination with a ##pid##, this value is not allowed to
start with ##"/"##.'
in: query
name: path
required: false
schema:
type: string
- description: 'The "PathID" is a path and encoding independant representation
of a specific filesystem object. Also returned and refered to as ##id##
in data related responses.
Example: ##d1372678008.d116##
Note: the ##pid## is not persistent upon changes (rename/move) to a filesystem
object.'
in: query
name: pid
required: false
schema:
type: string
- description: 'Name of an existing snapshot, as returned by [L[/#cv#/snapshot_GET]GET
/#cv#/snapshot].
If provided, the requested ##path## will be looked up inside the referenced
snapshot.'
in: query
name: snapshot
required: false
schema:
type: string
- description: 'This parameter is deprecated and ignored. All files are delivered
with the ##Content-Disposition## response header set to "attachment".'
in: query
name: attachment
required: false
schema:
type: boolean
responses:
'200':
content:
application/octet-stream:
schema:
format: binary
type: string
description: OK
'206':
description: Partial Content
'304':
description: Not Modified
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'416':
description: Requested Range Not Satisfiable
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: This endpoint can be used to retrieve single files
tags:
- file
patch:
description: "Do a partial update on a file.\nThe maximum size of a partial\
\ update is limited to 2147483647 (2G - 1). The file to update has to exist.\n\
\n**Usage details:**\n\nBoth, the ##pid## and ##path## parameters identify\
\ a filesystem object, at least one of them is always mandatory.\nIt is allowed\
\ to use both together, in which case ##pid## addresses a superior directory,\
\ and the value of ##path## is considered relative to that directory. (##<pid>/<path>##)\n\
\nThe ##offset## into the file is given as a query parameter. If the ##offset##\
\ is beyond the file end, the file is extended up to the offset. The 'Content-Range'\
\ header (RFC 2616 \xA714.16) is __not__ supported.\n\nThe message body contains\
\ the new file contents. A ##Content-Type## must be given in the request header\
\ that is neither \"multipart/*\" nor \"application/x-www-form-urlencoded\"\
\ - \"application/octet-stream\" is a reasonable choice.\n\nThe message body\
\ will replace the file contents at ##[offset, offset+sizeof(body)-1]##.\n\
##PATCH /2.1/file?pid=d1372678008.f482&path=baz.txt&offset=32768\nContent-Type:\
\ application/octet-stream\n\n\n... new contents for baz.txt at offset 32768\
\ ...\n##\n**Note:** This option is not available in web browsers, so it cannot\
\ be tested here interactively.\n\nYou can use a program like \"curl\" to\
\ test this option anyway:\n##$: curl -X PATCH \\\n -H 'Authorization:\
\ Bearer ...' \\\n -H 'Content-Type: application/octet-stream' \\\n \
\ --data-binary @partial.bin \\\n https://[API]/#cv#/file?path=root/users/user/file.bin\\\
&offset=49152\n##\n**Note of caution:**\nThis call can create so-called **sparse\
\ files**. Those may allocate less space on the file system than their appearent\
\ size indicates, since holes betweens data chunks are \"real\" holes and\
\ not areas of 0-bytes. The thing to consider is that subsequent data copy\
\ actions usually expand sparse data into 0-bytes.\nLong story short: Use\
\ this method carefully!"
parameters:
- description: 'The path to a filesystem object.
Example: ##/users/example/Music##
The shortest possible path is ##"/"##, which will always refer to the topmost
directory accessible by the authenticated user. For a regular HiDrive user
this is the HiDrive ##"root"##. If used with a [L[/#cv#/share/token_POST]share
access_token] it will be the shared directory.
Note: if used in combination with a ##pid##, this value is not allowed to
start with ##"/"##.'
in: query
name: path
required: false
schema:
type: string
- description: 'The "PathID" is a path and encoding independant representation
of a specific filesystem object. Also returned and refered to as ##id##
in data related responses.
Example: ##d1372678008.d116##
Note: the ##pid## is not persistent upon changes (rename/move) to a filesystem
object.'
in: query
name: pid
required: false
schema:
type: string
- description: 'The byte offset into the file.
Example: 49152'
in: query
name: offset
required: true
schema:
type: number
- description: The modification time (mtime) of the file system target to be
set after the operation.
in: query
name: mtime
required: false
schema:
type: number
responses:
'204':
description: No Content
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'413':
description: Request Entity Too Large
'500':
description: Internal Error
'507':
description: Insufficient Storage
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Do a partial update on a file
tags:
- file
post:
description: "This endpoint can be used to create a new file and store uploaded\
\ content.\n\nUsing POST guarantees that existing files will **not** be overwritten.\n\
If you wish to alter the contents of an existing file, use either [L[/#cv#/file_PUT]PUT\
\ /#cv#/file] or [L[/#cv#/file_PATCH]PATCH /#cv#/file].\n\n**Usage Details:**\n\
\nThe ##dir_id## and ##dir## parameters must be specified as query parameters\
\ of the URI.\nThey refer to the file's target directory on the HiDrive storage,\
\ at least one of the parameters is mandatory. If both are given, ##dir_id##\
\ addresses a directory, and the value of ##dir## is a relative path to that\
\ directory.\n\nThe maximum upload file size is limited to 2147483647 (2G\
\ - 1).\n\nAs existence of the target file will be checked only after the\
\ upload is complete, the target file may have sprung into existence during\
\ the upload. To avoid losing the uploaded content in this case, the optional\
\ ##on_exist## parameter can be set to \"autoname\". In that case, the returned\
\ data will contain a ##name##, that differs from the provided ##name## parameter.\n\
\n**Examples:**\n\nThere are two different options to use this endpoint, depending\
\ on the client's abilities.\n\n**First Option:**\nThe message body contains\
\ the upload file contents.\nA Content-Type must be given in the request header,\
\ that is neither \"multipart/*\" nor \"application/x-www-form-urlencoded\"\
\ - \"application/octet-stream\" is a reasonable choice.\n\nThe ##name## parameter\
\ contains the name of the file and must be given as a query parameter.\n\
##POST /#cv#/file?dir_id=d1372678008.d116&dir=foo/bar&name=baz.txt\nContent-Type:\
\ text/plain\n\n\n... contents of baz.txt ...\n##\nYou can use a program like\
\ \"curl\" to test this option:\n##curl -X POST \\\n -H 'Authorization:\
\ Bearer ...' \\\n -H 'Content-Type: image/gif' \\\n --data-binary @foo.gif\
\ \\\n https://[API]/#cv#/file?dir_id=d1372678008.d116&dir=foo/bar\\&name=foo.gif\n\
##\n**Second Option:**\nThis is the way how browsers upload a file. Please\
\ ask your favorite search engine for \"multipart/form-data\" and \"rfc2388\"\
.\nFor this option the filename itself must be included in the filename attribute\
\ of the upload data chunk. For browsers the filename is always the same on\
\ the local and on the remote host.\n**Note:** Browser implementations of\
\ RFC 6266 for non-ASCII filenames may be incomplete. Have a look at [L[http://greenbytes.de/tech/tc2231/]this\
\ page] for a detailed overview. Therefore, if possible, use the first option.\n\
##POST /#cv#/file?dir_id=d1372678008.d116&dir=foo/bar HTTP/1.1\nContent-Type:\
\ multipart/form-data; boundary=ufD8WlMu60b\n\n\n--ufD8WlMu60b\nContent-Disposition:\
\ form-data; name=\"name\"; filename=\"baz.txt\"\nContent-Type: text/plain\n\
\n\n... contents of baz.txt ...\n--ufD8WlMu60b--\n##\n"
parameters:
- description: '**Required** when ##dir_id## is not provided.
The path to the filesystem object, that shall be the target for the operation.
Example: ##/users/example/something##
The shortest possible path is ##"/"##, which will always refer to the topmost
directory accessible by the authenticated user. For a regular HiDrive user
this is the HiDrive ##"root"##. If used with a [L[/#cv#/share/token_POST]share
access_token] it will be the shared directory.
This value must not contain path elements ##"."## or ##".."## and must not
end with a slash ##"/"##.
Note: if used in combination with a ##dir_id##, this value is not allowed
to start with ##"/"## either.
Note: this is always a parent directory and must not contain the intended
filename. Use the ##name## parameter to specify the file name.'
in: query
name: dir
required: false
schema:
type: string
- description: '**Required** when ##dir## is not provided.
The "PathID" (##pid##) of the target filesystem object. (Or, if used in
combination with ##dir##, its superior directory.)
Example: ##d1372678008.d116##
Note: a ##pid## is not persistent upon changes (rename/move) to a filesystem
object. So after this operation, the ##dir_id## may no longer be valid.
However the current value will be part of the returned information (as ##parent_id##)
after a successful request.'
in: query
name: dir_id
required: false
schema:
type: string
- description: 'The intended filename.
The name parameter is mandatory for binary uploads. It is forbidden for
multipart/formdata uploads, where the name has to be specified as "filename"
parameter within the content-disposition header.'
in: query
name: name
required: false
schema:
$ref: '#/components/schemas/File'
- description: 'Optional parameter to determine the API behavior in case of
a conflict with an existing filesystem object.
**Possible value:**
##"autoname" - Find another name if the destination already exists.
"overwrite" - (not for directories) Replace destination object with source.
##
Note: when source and destination are the same, the operation results in
an ##error 409##.
Note: this operation only allows "autoname". For multipart/formdata uploads
this must be passed as a body-parameter.'
in: query
name: on_exist
required: false
schema:
type: string
- description: The modification time (mtime) of the file system target to be
set after the operation.
in: query
name: mtime
required: false
schema:
type: number
- description: The modification time (mtime) of the file system target's parent
folder to be set after the operation.
in: query
name: parent_mtime
required: false
schema:
type: number
responses:
'201':
description: Created
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'409':
description: Conflict
'413':
description: Request Entity Too Large
'415':
description: Unsupported Media Type
'422':
description: Unprocessable Entity (e.g. name too long)
'500':
description: Internal Error
'507':
description: Insufficient Storage
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: This endpoint can be used to create a new file and store uploaded content
tags:
- file
put:
description: 'Update a file by overwriting the target file with uploaded content.
If the target file does not exist it will be created.
If you wish to create a file without overwriting data, use [L[/#cv#/file_POST]POST
/#cv#/file].
For partial updates use: [L[/#cv#/file_PATCH]PATCH /#cv#/file].
**Usage Details:**
The ##dir_id## and ##dir## parameters must be specified as query parameters
of the URI.
They refer to the file''s target directory on the HiDrive storage, at least
one of the parameters is mandatory. If both are given, ##dir_id## addresses
a directory, and the value of ##dir## is a relative path to that directory.
The maximum upload file size is limited to 2147483647 (2G - 1).
**Examples:**
There are two different options to use this endpoint, depending on the client''s
abilities.
**First Option:**
The message body contains the upload file contents.
A Content-Type must be given in the request header, that is neither "multipart/*"
nor "application/x-www-form-urlencoded" - "application/octet-stream" is a
reasonable choice.
The ##name## parameter contains the name of the file and must be given as
a query parameter.
##PUT /2.1/file?dir=root/users/foo/bar&name=baz.txt
Content-Type: text/plain
... contents of baz.txt ...
##
**Second Option:**
This is the way how browsers upload a file. Please ask your favorite search
engine for "multipart/form-data" and "rfc2388".
For this option the filename itself must be included in the filename attribute
of the upload data chunk. For browsers the filename is always the same on
the local and on the remote host.
**Note:** Browser implementations of RFC 6266 for non-ASCII filenames may
be incomplete. Have a look at [L[http://greenbytes.de/tech/tc2231/]this page]
for a detailed overview. Therefore, if possible, use the first option.
##PUT /2.1/file?dir_id=d1372678008.d116&dir=foo/bar
Content-Type: multipart/form-data; boundary=ufD8WlMu60b
--ufD8WlMu60b
Content-Disposition: form-data; name="name"; filename="baz.txt"
Content-Type: text/plain
... contents of baz.txt ...
--ufD8WlMu60b--
##
'
parameters:
- description: '**Required** when ##dir_id## is not provided.
The path to the filesystem object, that shall be the target for the operation.
Example: ##/users/example/something##
The shortest possible path is ##"/"##, which will always refer to the topmost
directory accessible by the authenticated user. For a regular HiDrive user
this is the HiDrive ##"root"##. If used with a [L[/#cv#/share/token_POST]share
access_token] it will be the shared directory.
This value must not contain path elements ##"."## or ##".."## and must not
end with a slash ##"/"##.
Note: if used in combination with a ##dir_id##, this value is not allowed
to start with ##"/"## either.
Note: this is always a parent directory and must not contain the intended
filename. Use the ##name## parameter to specify the file name.'
in: query
name: dir
required: false
schema:
type: string
- description: '**Required** when ##dir## is not provided.
The "PathID" (##pid##) of the target filesystem object. (Or, if used in
combination with ##dir##, its superior directory.)
Example: ##d1372678008.d116##
Note: a ##pid## is not persistent upon changes (rename/move) to a filesystem
object. So after this operation, the ##dir_id## may no longer be valid.
However the current value will be part of the returned information (as ##parent_id##)
after a successful request.'
in: query
name: dir_id
required: false
schema:
type: string
- description: 'The intended filename.
The name parameter is mandatory for binary uploads. It is forbidden for
multipart/formdata uploads, where the name has to be specified as "filename"
parameter within the content-disposition header.'
in: query
name: name
required: false
schema:
$ref: '#/components/schemas/File'
- description: The modification time (mtime) of the file system target to be
set after the operation.
in: query
name: mtime
required: false
schema:
type: number
- description: The modification time (mtime) of the file system target's parent
folder to be set after the operation.
in: query
name: parent_mtime
required: false
schema:
type: number
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'413':
description: Request Entity Too Large
'415':
description: Unsupported Media Type
'422':
description: Unprocessable Entity (e.g. name too long)
'500':
description: Internal Error
'507':
description: Insufficient Storage
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Update a file by overwriting the target file with uploaded content
tags:
- file
/file/archive:
get:
description: 'Get information about an archive file and its contents.
At the moment only **Zip** archives are supported.
The Endpoint supports the [L[https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT]PKWare
Zip64-Extension]
Both, the ##pid## and ##path## parameters identify a filesystem object, at
least one of them is always mandatory.
It is allowed to use both together, in which case ##pid## addresses a superior
directory, and the value of ##path## is considered relative to that directory.
(##<pid>/<path>##)
To get the contents of a snapshot, use the ##path## parameter and the name
of a snapshot in the ##snapshot## parameter. The name must be UTF-8 encoded.
Available snapshot-names can be requested via [L[/#cv#/snapshot_GET]GET /#cv#/snapshot].
It is also possible to reference objects in snapshots by their ##pid##, however,
in this case the ##snapshot## parameter is neither needed nor allowed.'
parameters:
- description: 'The path to a filesystem object.
Example: ##/users/example/Music##
The shortest possible path is ##"/"##, which will always refer to the topmost
directory accessible by the authenticated user. For a regular HiDrive user
this is the HiDrive ##"root"##. If used with a [L[/#cv#/share/token_POST]share
access_token] it will be the shared directory.
Note: if used in combination with a ##pid##, this value is not allowed to
start with ##"/"##.'
in: query
name: path
required: false
schema:
type: string
- description: 'The "PathID" is a path and encoding independant representation
of a specific filesystem object. Also returned and refered to as ##id##
in data related responses.
Example: ##d1372678008.d116##
Note: the ##pid## is not persistent upon changes (rename/move) to a filesystem
object.'
in: query
name: pid
required: false
schema:
type: string
- description: 'Name of an existing snapshot, as returned by [L[/#cv#/snapshot_GET]GET
/#cv#/snapshot].
If provided, the requested ##path## will be looked up inside the referenced
snapshot.'
in: query
name: snapshot
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'415':
description: Unsupported Media Type
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Get information about an archive file and its contents
tags:
- file
/file/archive/deflate:
post:
description: "Pack files into an archive file.\nAt the moment only **Zip** archives\
\ are supported.\n\nThe Endpoint supports the [L[https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT]PKWare\
\ Zip64-Extension]\n\nThe parameters ##src## and ##src_id## as well as ##dst##\
\ and ##dst_id## identify the source and destination for the operation. At\
\ least one source identifier and ##dst## are always mandatory.\nIt is allowed\
\ to use the related parameters together, in which case ##src_id## and ##dst_id##\
\ each addresses a superior directory, and the values of ##src## and ##dst##\
\ are considered relative to that directory. (e.g.##<src_id>/<src>##) Any\
\ number of ##src## parameters is allowed.\n\nThe use of optional ##base##/##base_id##\
\ is analogous, besides it needs to refer to a directory. (see parameter description)\n\
\n**A note about sparse files:**\n\nZIP archives are not able to store file\
\ sparse information, sparse areas are simply stored as a stream of 0-bytes.\
\ That means, while a series of 0-bytes is compressed fairly well and does\
\ not increase the archive file noticeably, the originally sparse file will\
\ be expanded into a non-sparse file in a subsequent inflate operation.\n\n\
See notes about sparse files in [L[/#cv#/file_PATCH]PATCH /#cv#/file] and\
\ [L[/#cv#/file/truncate_POST]POST /#cv#/file/truncate].\n\n**Example request**\
\ (with linefeeds for readability):\n##POST /file/archive/deflate\nContent-Type:\
\ application/x-www-form-urlencoded\n dst=root%2Fusers%2Ffoobar%2Froundup.zip&\n\
\ base=root%2Fusers%2Ffoobar%2FDocs&\n src=root%2Fusers%2Ffoobar%2FDocs%2Fspendings.xls&\n\
\ src=root%2Fusers%2Ffoobar%2Fnotexists.txt&\n src=root%2Fusers%2Ffoobar%2FLetterToJane.doc&\n\
\ src=root%2Fusers%2Ffoobar%2Fbank%2F2011-Aug.pdf\n##\n"
parameters:
- description: 'The path to the filesystem object, that shall be the destination
for the operation.
Example: ##/users/example/archive/something##
Note: if used in combination with a ##dst_id##, this value is not allowed
to start with ##"/"##.
Note: An existing archive file will be overwritten.'
in: query
name: dst
required: true
schema:
type: string
- description: 'Without ##dst## parameter:
This refers to an archive file, which shall be the destination of the operation.
With ##dst##:
This is the path ID of a superior directory of the archive file provided
as a relative path in ##dst##.'
in: query
name: dst_id
required: false
schema:
type: string
- description: 'The local path to a directory, that shall be the base for all
paths specified in ##src##.
All filenames in the archive will be created relative to ##base## and ##base_id##.
The synopsis in the description example would create the filenames "spendings.xls",
"../LetterToJane.doc" and "../bank/2011-Aug.pdf". The default is to use
the parent directory of ##dst##.'
in: query
name: base
required: false
schema:
type: string
- description: 'Example: ##b1490712797.1069533##
Without ##base## parameter:
This refers to a directory, which shall be the base of the files within
the archive.
With ##base##:
This is the path ID of a superior directory of the directory provided as
a relative path in ##base##.
If ##base## and ##src## are equal the content of the Directory as given
in ##base## will be included in the Archive.'
in: query
name: base_id
required: false
schema:
type: string
- description: 'The path to the filesystem object, that shall be the source
for the operation.
Example: ##/users/example/something##
It is not allowed to use only ##"/"## as a source, since it is the parent
for all possible targets.
Note: if used in combination with a ##src_id##, this value is not allowed
to start with ##"/"## either.
Note: There can be multiple ##src## values in one call.'
in: query
name: src
required: true
schema:
items:
type: string
type: array
- description: 'The "PathID" (##pid##) of the source filesystem object. (Or,
if used in combination with ##src##, its superior directory.)
Example: ##d1372678008.d116##
Note: a ##pid## is not persistent upon changes (rename/move) to a filesystem
object. So after this operation, the ##src_id## may no longer be valid.
However the current value will be part of the returned information (as ##id##)
after a successful request.
Note: There can be multiple values for ##src_id## **unless** if used in
conjunction with ##src##. In this case only one ##src_id## parameter is
allowed, that refers to a superior directory of all paths specified by ##src##.'
in: query
name: src_id
required: false
schema:
items:
type: string
type: array
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'207':
description: Multi-Status (body contains multiple status messages)
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Error
'504':
description: Gateway Timeout
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Pack files into an archive file
tags:
- file
/file/archive/download:
post:
description: "Pack files into a (zip) archive and stream to client.\nAt the\
\ moment only **Zip** archives are supported.\n\nThe Endpoint supports the\
\ [L[https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT]PKWare Zip64-Extension]\n\
\nBoth, the ##src_id## and ##src## parameters refer to source files or directories,\
\ at least one of them is mandatory. If both are given, only one ##src_id##\
\ parameter and any number of 'src' parameters is allowed. ##src_id## addresses\
\ a superior directory, and the values of 'src' are relative paths to the\
\ actual source files or directories.\n\n**Usage details:**\n\nAn HTTP/1.1\
\ request is answered with a chunked transfer encoding response, whereas a\
\ HTTP/1.0 request gets a response without any Content-Length information,\
\ and the connection is closed at the end of the response.\n\nTo get the contents\
\ of a snapshot, use the ##path## parameter and the name of a snapshot in\
\ the ##snapshot## parameter. The name must be UTF-8 encoded. Available snapshot-names\
\ can be requested via [L[/#cv#/snapshot_GET]GET /#cv#/snapshot].\nIt is also\
\ possible to reference objects in snapshots by their ##pid##, however, in\
\ this case the ##snapshot## parameter is neither needed nor allowed.\n\n\
**Example request:** (with linefeeds for readability)\n##POST /file/archive/download\n\
Content-Type: application/x-www-form-urlencoded\n base=root%2Fusers%2Ffoobar%2FDocs&\n\
\ src=root%2Fusers%2Ffoobar%2FDocs%2Fspendings.xls&\n src=root%2Fusers%2Ffoobar%2FLetterToJane.doc&\n\
\ src=root%2Fusers%2Ffoobar%2Fbank%2F2011-Aug.pdf\n##\nThe resulting archive\
\ will contain the following members:\n##spendings.xls\n../LetterToJane.doc\n\
bank/2011-Aug.pdf\n##\n**Note:** The API does not guarantee that all requested\
\ files and directories will be included in the streamed response. There is\
\ the slight possibility that parallel actions (i.e. uploads or deletes) might\
\ affect the provided ##src## objects before they are incorporated in the\
\ streamed data. There are, however, ways to prevent this type of interference.\
\ See [L[https://dev.strato.com/hidrive/showthread.php?t=42]more details]."
parameters:
- description: 'The path to the filesystem object, that shall be the source
for the operation.
Example: ##/users/example/something##
It is not allowed to use only ##"/"## as a source, since it is the parent
for all possible targets.
Note: if used in combination with a ##src_id##, this value is not allowed
to start with ##"/"## either.
Note: There can be multiple ##src## values in one call.'
in: query
name: src
required: true
schema:
items:
type: string
type: array
- description: 'The "PathID" (##pid##) of the source filesystem object. (Or,
if used in combination with ##src##, its superior directory.)
Example: ##d1372678008.d116##
Note: a ##pid## is not persistent upon changes (rename/move) to a filesystem
object. So after this operation, the ##src_id## may no longer be valid.
However the current value will be part of the returned information (as ##id##)
after a successful request.
Note: There can be multiple values for ##src_id## **unless** if used in
conjunction with ##src##. In this case only one ##src_id## parameter is
allowed, that refers to a superior directory of all paths specified by ##src##.'
in: query
name: src_id
required: false
schema:
items:
type: string
type: array
- description: 'The local path to a directory, that shall be the base for all
paths specified in ##src##.
Example: ##/user/example/##.
All filenames in the archive will be created relative to ##base## and ##base_id##.
'
in: query
name: base
required: true
schema:
type: string
- description: 'Example: ##b1490712797.1069533##
Without ##base## parameter:
This refers to a directory, which shall be the base of the files within
the archive.
With ##base##:
This is the path ID of a superior directory of the directory provided as
a relative path in ##base##.
If ##base## and ##src## are equal the content of the Directory as given
in ##base## will be included in the Archive.'
in: query
name: base_id
required: false
schema:
type: string
- description: 'Name of an existing snapshot, as returned by [L[/#cv#/snapshot_GET]GET
/#cv#/snapshot].
If provided, the requested ##path## will be looked up inside the referenced
snapshot. This applies to all paths provided as ##src##.'
in: query
name: snapshot
required: false
schema:
type: string
responses:
'200':
content:
application/octet-stream:
schema:
format: binary
type: string
description: OK
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'500':
description: Internal Error
'504':
description: Gateway Timeout
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Pack files into a (zip) archive and stream to client
tags:
- file
/file/archive/inflate:
post:
description: 'Unpack files from an archive file.
At the moment only **Zip** archives are supported.
The Endpoint supports the [L[https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT]PKWare
Zip64-Extension]
Both, the ##pid## and ##path## parameters identify a filesystem object, at
least one of them is always mandatory.
It is allowed to use both together, in which case ##pid## addresses a superior
directory, and the value of ##path## is considered relative to that directory.
(##<pid>/<path>##) Similar behavior is true for ##dst_id## and ##dst##.
Without ##dst## or ##dst_id##, the archive members will be unpacked relative
to the archive directory. If they refer to an existing, writable directory
the archive members will be unpacked there.
**Further details**
An archive contains an ordered list of archive members that are always processed
in the same order.
By default, unpacking will stop when an error occurs.
For example, the archive member may already exist or the target file cannot
be created because a directory is not writable. Aborts are marked with one
of the following status codes:
##403 Forbidden
409 Conflict
422 Unprocessable Entity
504 Gateway Timeout
##
In that situation, the response field ##break_at## contains the archive member''s
path, that caused the processing failure. This value can be used as the ##start_with##
parameter to restart unpacking at that position in the next API call.
All errors except ##504## require an additional parameter that defines how
to cope with that type of error in the subsequent call.
See the description for parameters ##forbidden##, ##exists## and ##unprocessable##.
**Note:** Archive members with absolute paths are converted to relative paths
by removing all leading slashes.
**Note:** Unpacking an archive that contains paths parts to an upper directory
(##".."##) may require careful consideration of the ##dst## parameter to avoid
''##403 Forbidden##'' responses.'
parameters:
- description: 'The path to a filesystem object.
Example: ##/users/example/Music##
The shortest possible path is ##"/"##, which will always refer to the topmost
directory accessible by the authenticated user. For a regular HiDrive user
this is the HiDrive ##"root"##. If used with a [L[/#cv#/share/token_POST]share
access_token] it will be the shared directory.
Note: if used in combination with a ##pid##, this value is not allowed to
start with ##"/"##.'
in: query
name: path
required: false
schema:
type: string
- description: 'The "PathID" is a path and encoding independant representation
of a specific filesystem object. Also returned and refered to as ##id##
in data related responses.
Example: ##d1372678008.d116##
Note: the ##pid## is not persistent upon changes (rename/move) to a filesystem
object.'
in: query
name: pid
required: false
schema:
type: string
- description: 'Name of an existing snapshot, as returned by [L[/#cv#/snapshot_GET]GET
/#cv#/snapshot].
If provided, the requested ##path## will be looked up inside the referenced
snapshot.'
in: query
name: snapshot
required: false
schema:
type: string
- description: 'The path to the filesystem object, that shall be the destination
for the operation.
Example: ##/users/example/archive/something##
Note: if used in combination with a ##dst_id##, this value is not allowed
to start with ##"/"##.'
in: query
name: dst
required: false
schema:
type: string
- description: 'If provided, this must always be the ##pid## of a superior directory
of the ##dst##.
Example: d1372678008.d117'
in: query
name: dst_id
required: false
schema:
type: string
- description: 'This optional parameter defines how existing files are handled.
**Possible values are:**
##break: Terminate unpacking at the first existing file (default)
all: Overwrite all existing files with content from archive
next: Overwrite only the next existing file
skipnext: Skip only the next existing file
skipall: Skip all existing files
##
'
in: query
name: exists
required: false
schema:
type: string
- description: 'This optional parameter defines how files are handled, that
the user is not allowed to (over-)write.
**Possible values are:**
##break: Terminate unpacking at the first forbidden file (default)
skipnext: Skip only the next forbidden file
skipall: Skip all forbidden files
##
'
in: query
name: forbidden
required: false
schema:
type: string
- description: 'This optional parameter defines how ''unprocessable'' errors
ought to be handled. This applies to encryted archive members, which are
not supported.
**Possible values are:**
##break: Terminate unpacking at the first unprocessable member (default)
skipnext: Skip only the next unprocessable member
skipall: Skip all unprocessable members
##
'
in: query
name: unprocessable
required: false
schema:
type: string
- description: 'Skip inflation for all files in the archive until reaching the
**path** given in this parameter.
Since inflation always starts from the beginning and happens in the same
order, ##start_with## is especially useful in conjunction with the ##exists##
and ##forbidden## parameters, in order to build an "Overwrite? Yes/No/All/Cancel"
or "Skip? Yes/All/Cancel" dialog.'
in: query
name: start_with
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'409':
description: Conflict
'415':
description: Unsupported Media Type
'422':
description: Unprocessable Entity (e.g. encrypted contents)
'500':
description: Internal Error
'504':
description: Gateway Timeout
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Unpack files from an archive file
tags:
- file
/file/copy:
post:
description: 'Copy a file.
The parameters ##src## and ##src_id## as well as ##dst## and ##dst_id## identify
the source and destination for the operation. At least one source identifier
and ##dst## are always mandatory.
It is allowed to use the related parameters together, in which case ##src_id##
and ##dst_id## each addresses a superior directory, and the values of ##src##
and ##dst## are considered relative to that directory. (e.g.##<src_id>/<src>##)
To copy data from a snapshot directory, use the ##src## parameter and the
name of a snapshot in the ##snapshot## parameter. The name must be UTF-8 encoded.
Available snapshot-names can be requested via [L[/#cv#/snapshot_GET]GET /#cv#/snapshot].
It is also possible to reference objects in snapshots by their ##pid## (provided
as ##src_id##), however, in this case the ##snapshot## parameter is neither
needed nor allowed.
**A note about sparse files:**
Copying a sparse file does not preserve sparse-ness on the destination: Sparse
areas in the source are expanded to blocks of 0-bytes in the destination.
See notes about sparse files in [L[/#cv#/file_PATCH]PATCH /#cv#/file] and
[L[/#cv#/file/truncate_POST]POST /#cv#/file/truncate].'
parameters:
- description: 'The path to the filesystem object, that shall be the source
for the operation.
Example: ##/users/example/something##
It is not allowed to use only ##"/"## as a source, since it is the parent
for all possible targets.
Note: if used in combination with a ##src_id##, this value is not allowed
to start with ##"/"## either.'
in: query
name: src
required: false
schema:
type: string
- description: 'The "PathID" (##pid##) of the source filesystem object. (Or,
if used in combination with ##src##, its superior directory.)
Example: ##d1372678008.d116##
Note: a ##pid## is not persistent upon changes (rename/move) to a filesystem
object. So after this operation, the ##src_id## may no longer be valid.
However the current value will be part of the returned information (as ##id##)
after a successful request.'
in: query
name: src_id
required: false
schema:
type: string
- description: 'The path to the filesystem object, that shall be the destination
for the operation.
Example: ##/users/example/archive/something##
Note: if used in combination with a ##dst_id##, this value is not allowed
to start with ##"/"##.'
in: query
name: dst
required: true
schema:
type: string
- description: 'If provided, this must always be the ##pid## of a superior directory
of the ##dst##.
Example: d1372678008.d117'
in: query
name: dst_id
required: false
schema:
type: string
- description: 'Optional parameter to determine the API behavior in case of
a conflict with an existing filesystem object.
**Possible value:**
##"autoname" - Find another name if the destination already exists.
"overwrite" - (not for directories) Replace destination object with source.
##
Note: when source and destination are the same, the operation results in
an ##error 409##.'
in: query
name: on_exist
required: false
schema:
type: string
- description: 'Name of an existing snapshot, as returned by [L[/#cv#/snapshot_GET]GET
/#cv#/snapshot].
If provided, the requested ##path## will be looked up inside the referenced
snapshot.'
in: query
name: snapshot
required: false
schema:
type: string
- description: The modification time (mtime) of the destination parent folder
to be set after the operation.
in: query
name: dst_parent_mtime
required: false
schema:
type: number
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'409':
description: Conflict
'422':
description: Unprocessable Entity (e.g. name too long)
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Copy a file
tags:
- file
/file/hash:
get:
description: 'Get partial hashes for a file object. At least one of the parameters
path and pid is mandatory. If both are given, pid must address a directory,
and the value of path is a relative path from that directory.
To get data from a snapshot, the name of the snapshot must be provided in
the snapshot parameter. The name must be UTF-8 encoded.'
parameters:
- description: 'Local path to the object.
Example: root/users/foobar/Music/file.ext'
in: query
name: path
required: false
schema:
type: string
- description: 'The public id of the object.
Example: F<d1372678008.f482>'
in: query
name: pid
required: false
schema:
type: string
- description: 'Name of snapshot. Note: Mutually exclusive with the pid parameter,
since a public id may reference something in a snapshot.'
in: query
name: snapshot
required: false
schema:
type: string
- description: Level of hashes requested
in: query
name: level
required: true
schema:
type: number
- description: 'Comma-separated list of requested ranges of the form <from>-<to>.
If <from> is ommitted, 0 is assumed. if <to> is ommitted, the range to the
end of the file is assumed. For level 0 requests, the maximum number of
hashes requested is limited to 256 per range to prevent excessive output.
Furthermore, for level 0 an explicit <from> and <to> must be given. <from>
and <to> are given as file offsets. Example: ranges=-10000000,20000000-30000000,40000000-
For a detailed description of Hashes see <here>.
default: all'
in: query
name: ranges
required: true
schema:
type: number
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (no authentication)
'403':
description: 'Forbidden (e.g. forbidden: acl)'
'404':
description: Not Found (e.g. file not existing)
'415':
description: Unsupported Media Type (requested object is not a file)
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Get partial hashes for a file object
tags:
- file
/file/image/autoorient:
post:
description: 'Rotate an image file by it''s exif orientation. Afterwards the
exif orientation of the image file is reset.
Both, the "pid" and "path" parameters refer to the file, at least one of them
is mandatory. If both are given, "pid" addresses a superior directory, and
the value of "path" is a relative path to that directory. Only jpeg and tiff
files are supported.
Similarly ''dst_id'' and ''dst'' refer to the destination file. If ''dst_id''
or ''dst'' is given alone, it addresses the destination directly, otherwise
''dst_id'' refers to a superior directory, and ''dst'' is the relative path
from that directory to the destination image file.
File will be manipulated in place, if param ''dst''/''dst_id'' is not given.
An existing file at ''dst''/''dst_id'' will be silently overwritten.'
parameters:
- description: 'Path to an existing image file. Example: root/users/foobar/source.jpg'
in: query
name: path
required: false
schema:
type: string
- description: 'The public id of the file or public id of a superior directory
if ''path'' is given.
Example: F<d1372678008.f482>'
in: query
name: pid
required: false
schema:
type: string
- description: 'Target Path for the resulting image file. Example: root/users/foobar/scaled.jpg
(see description)'
in: query
name: dst
required: false
schema:
type: string
- description: Referes to a directory, which is either the destination directory,
if no 'dst' parameter is given, or a superior directory of the destination,
and the value of 'src' is a relative path.
in: query
name: dst_id
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (no authentication)
'403':
description: 'Forbidden (e.g. forbidden: acl)'
'404':
description: Not found (e.g. image not existing)
'415':
description: Unsupported Media Type (e.g. not an image)
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Rotate an image file by it's exif orientation
tags:
- file
/file/image/combined:
post:
description: "Combine image operations [L[/#cv#/file/image/scale_POST]POST /#cv#/file/image/scale],\
\ [L[/#cv#/file/image/autoorient_POST]POST /#cv#/file/image/autoorient], [L[/#cv#/file/image/crop_POST]POST\
\ /#cv#/file/image/crop] and [L[/#cv#/file/image/rotate_POST]POST /#cv#/file/image/rotate]\
\ in one call.\n\nThe order in which to execute these operations is specified\
\ in ##order##. Each operation can only appear once per call.\n\n**Example\
\ call:**\n##/combined\n ?path=...\n &order=RCS\n &rotate_degrees=-10\n\
\ &scale_width=50\n &crop_width=100\n &crop_height=50\n##\nRotates\
\ the source image counter-clockwise by 10 degrees, crops a 100x50 pixel rectangle\
\ from the upper left corner and then scales it down to a width of 50px (the\
\ final height will be 25px).\n\nBoth, the ##pid## and ##path## parameters\
\ identify a filesystem object, at least one of them is always mandatory.\n\
It is allowed to use both together, in which case ##pid## addresses a superior\
\ directory, and the value of ##path## is considered relative to that directory.\
\ (##<pid>/<path>##)\nSimilarly ##dst_id## and ##dst## refer to the destination\
\ file.\n\nThe File will be manipulated in place, if neither ##dst## nor ##dst_id##\
\ is provided. An existing destination file will be silently overwritten.\
\ (no Error: 409)"
parameters:
- description: 'The path to a filesystem object.
Example: ##/users/example/Music##
The shortest possible path is ##"/"##, which will always refer to the topmost
directory accessible by the authenticated user. For a regular HiDrive user
this is the HiDrive ##"root"##. If used with a [L[/#cv#/share/token_POST]share
access_token] it will be the shared directory.
Note: if used in combination with a ##pid##, this value is not allowed to
start with ##"/"##.'
in: query
name: path
required: false
schema:
type: string
- description: 'The "PathID" is a path and encoding independant representation
of a specific filesystem object. Also returned and refered to as ##id##
in data related responses.
Example: ##d1372678008.d116##
Note: the ##pid## is not persistent upon changes (rename/move) to a filesystem
object.'
in: query
name: pid
required: false
schema:
type: string
- description: 'Order of operations /[SCRA]{1,4}/
##S - Scale
C - Crop
R - Rotate
A - Autoorient
##
'
in: query
name: order
required: true
schema:
type: string
- description: 'If provided, this must always be the ##pid## of a superior directory
of the ##dst##.
Example: d1372678008.d117'
in: query
name: dst_id
required: false
schema:
type: string
- description: Scale to width (keeping proportions)
in: query
name: scale_width
required: false
schema:
type: number
- description: Scale to height (keeping proportions)
in: query
name: scale_height
required: false
schema:
type: number
- description: Scale to max height or width (keeping proportions)
in: query
name: scale_max
required: false
schema:
type: number
- description: Scale by factor from 0.0 (only positive values). Using this parameter
the image can be scaled down (0.0 < factor < 1.0) or up (1.0 < factor) while
maintaining the aspect ratio.
in: query
name: scale_factor
required: false
schema:
type: number
- description: 'Rotate by degrees.
degrees > 0 = clockwise degrees < 0 = counter-clockwise'
in: query
name: rotate_degrees
required: false
schema:
type: number
- description: Width of the new cropping pane
in: query
name: crop_width
required: false
schema:
type: number
- description: Height of the new cropping pane
in: query
name: crop_height
required: false
schema:
type: number
- description: X-Offset for cropping
in: query
name: crop_x
required: false
schema:
type: number
- description: Y-Offest for cropping
in: query
name: crop_y
required: false
schema:
type: number
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'415':
description: Unsupported Media Type
'422':
description: Unprocessable Entity
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Combine image operations [L[/#cv#/file/image/scale_POST]POST /#cv#/file/image/scale],
[L[/#cv#/file/image/autoorient_POST]POST /#cv#/file/image/autoorient], [L[/#cv#/file/image/crop_POST]POST
/#cv#/file/image/crop] and [L[/#cv#/file/image/rotate_POST]POST /#cv#/file/image/rotate]
in one call
tags:
- file
/file/image/crop:
post:
description: 'Crops an image file.
The crop rectangle is described by ##width## and ##height## (pixels). When
##x## and ##y## are not given, the crop rectangle will be placed at the image
origin (0,0) which is in the upper, left corner.
Offsets are zero based.
Both, the ##pid## and ##path## parameters identify a filesystem object, at
least one of them is always mandatory.
It is allowed to use both together, in which case ##pid## addresses a superior
directory, and the value of ##path## is considered relative to that directory.
(##<pid>/<path>##)
Similarly ##dst_id## and ##dst## refer to the destination file.
The File will be manipulated in place, if neither ##dst## nor ##dst_id## is
provided. An existing destination file will be silently overwritten. (no Error:
409)'
parameters:
- description: 'The path to a filesystem object.
Example: ##/users/example/Music##
The shortest possible path is ##"/"##, which will always refer to the topmost
directory accessible by the authenticated user. For a regular HiDrive user
this is the HiDrive ##"root"##. If used with a [L[/#cv#/share/token_POST]share
access_token] it will be the shared directory.
Note: if used in combination with a ##pid##, this value is not allowed to
start with ##"/"##.'
in: query
name: path
required: false
schema:
type: string
- description: 'The "PathID" is a path and encoding independant representation
of a specific filesystem object. Also returned and refered to as ##id##
in data related responses.
Example: ##d1372678008.d116##
Note: the ##pid## is not persistent upon changes (rename/move) to a filesystem
object.'
in: query
name: pid
required: false
schema:
type: string
- description: 'The path to the filesystem object, that shall be the destination
for the operation.
Example: ##/users/example/archive/something##
Note: if used in combination with a ##dst_id##, this value is not allowed
to start with ##"/"##.'
in: query
name: dst
required: false
schema:
type: string
- description: 'If provided, this must always be the ##pid## of a superior directory
of the ##dst##.
Example: d1372678008.d117'
in: query
name: dst_id
required: false
schema:
type: string
- description: Width of the new pane in pixels.
in: query
name: width
required: false
schema:
type: number
- description: Height of the new pane in pixels.
in: query
name: height
required: false
schema:
type: number
- description: X-Offset for cropping in pixels
in: query
name: x
required: false
schema:
type: number
- description: Y-Offest for cropping in pixels
in: query
name: y
required: false
schema:
type: number
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'415':
description: Unsupported Media Type
'422':
description: Unprocessable Entity
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Crops an image file
tags:
- file
/file/image/rotate:
post:
description: 'Rotate an image file by ##degrees##,
given as a floating point number (used modulo 360, with 1/10th degree precision).
Negative numbers rotate counter-clockwise.
Both, the ##pid## and ##path## parameters identify a filesystem object, at
least one of them is always mandatory.
It is allowed to use both together, in which case ##pid## addresses a superior
directory, and the value of ##path## is considered relative to that directory.
(##<pid>/<path>##)
Similarly ##dst_id## and ##dst## refer to the destination file.
The File will be manipulated in place, if neither ##dst## nor ##dst_id## is
provided. An existing destination file will be silently overwritten. (no Error:
409)'
parameters:
- description: 'The path to a filesystem object.
Example: ##/users/example/Music##
The shortest possible path is ##"/"##, which will always refer to the topmost
directory accessible by the authenticated user. For a regular HiDrive user
this is the HiDrive ##"root"##. If used with a [L[/#cv#/share/token_POST]share
access_token] it will be the shared directory.
Note: if used in combination with a ##pid##, this value is not allowed to
start with ##"/"##.'
in: query
name: path
required: false
schema:
type: string
- description: 'The "PathID" is a path and encoding independant representation
of a specific filesystem object. Also returned and refered to as ##id##
in data related responses.
Example: ##d1372678008.d116##
Note: the ##pid## is not persistent upon changes (rename/move) to a filesystem
object.'
in: query
name: pid
required: false
schema:
type: string
- description: 'The path to the filesystem object, that shall be the destination
for the operation.
Example: ##/users/example/archive/something##
Note: if used in combination with a ##dst_id##, this value is not allowed
to start with ##"/"##.'
in: query
name: dst
required: false
schema:
type: string
- description: 'If provided, this must always be the ##pid## of a superior directory
of the ##dst##.
Example: d1372678008.d117'
in: query
name: dst_id
required: false
schema:
type: string
- description: 'Rotate the file by the given degrees.
Example:
##degrees = 45.0 - rotate 45 degrees clockwise
degrees = -45.0 - rotate 45 degrees counter-clockwise
##
'
in: query
name: degrees
required: true
schema:
type: number
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'415':
description: Unsupported Media Type
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: 'Rotate an image file by ##degrees##,'
tags:
- file
/file/image/scale:
post:
description: 'Scale an image file with a variety of options.
Both, the ##pid## and ##path## parameters identify a filesystem object, at
least one of them is always mandatory.
It is allowed to use both together, in which case ##pid## addresses a superior
directory, and the value of ##path## is considered relative to that directory.
(##<pid>/<path>##)
Similarly ##dst_id## and ##dst## refer to the destination file.
The File will be manipulated in place, if neither ##dst## nor ##dst_id## is
provided. An existing destination file will be silently overwritten. (no Error:
409)'
parameters:
- description: 'The path to a filesystem object.
Example: ##/users/example/Music##
The shortest possible path is ##"/"##, which will always refer to the topmost
directory accessible by the authenticated user. For a regular HiDrive user
this is the HiDrive ##"root"##. If used with a [L[/#cv#/share/token_POST]share
access_token] it will be the shared directory.
Note: if used in combination with a ##pid##, this value is not allowed to
start with ##"/"##.'
in: query
name: path
required: false
schema:
type: string
- description: 'The "PathID" is a path and encoding independant representation
of a specific filesystem object. Also returned and refered to as ##id##
in data related responses.
Example: ##d1372678008.d116##
Note: the ##pid## is not persistent upon changes (rename/move) to a filesystem
object.'
in: query
name: pid
required: false
schema:
type: string
- description: 'The path to the filesystem object, that shall be the destination
for the operation.
Example: ##/users/example/archive/something##
Note: if used in combination with a ##dst_id##, this value is not allowed
to start with ##"/"##.'
in: query
name: dst
required: false
schema:
type: string
- description: 'If provided, this must always be the ##pid## of a superior directory
of the ##dst##.
Example: d1372678008.d117'
in: query
name: dst_id
required: false
schema:
type: string
- description: 'Scale to width in pixels.
If only one of ##width## or ##height## are provided, the image will be scaled
to the target size maintaining the aspect ratio.
When both are given, the image will be distorted to fit the target size.'
in: query
name: width
required: false
schema:
type: number
- description: 'Scale to height in pixels.
If only one of ##width## or ##height## are provided, the image will be scaled
to the target size maintaining the aspect ratio.
When both are given, the image will be distorted to fit the target size.'
in: query
name: height
required: false
schema:
type: number
- description: 'Scale longer edge to max value in pixels (proportional).
Use ##max## to define the target length of the longer edge. Example:
##input: 600x400
max: 100
output: 100x66
input: 200x400
max: 100
output: 50x100
##
'
in: query
name: max
required: false
schema:
type: number
- description: Scale by factor from 0.0 (only positive values). Using this parameter
the image can be scaled down (0.0 < factor < 1.0) or up (1.0 < factor) while
maintaining the aspect ratio.
in: query
name: factor
required: false
schema:
type: number
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'415':
description: Unsupported Media Type
'422':
description: Unprocessable Entity
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Scale an image file with a variety of options
tags:
- file
/file/move:
post:
description: 'Move a file.
The parameters ##src## and ##src_id## as well as ##dst## and ##dst_id## identify
the source and destination for the operation. At least one source identifier
and ##dst## are always mandatory.
It is allowed to use the related parameters together, in which case ##src_id##
and ##dst_id## each addresses a superior directory, and the values of ##src##
and ##dst## are considered relative to that directory. (e.g.##<src_id>/<src>##)'
parameters:
- description: 'The path to the filesystem object, that shall be the source
for the operation.
Example: ##/users/example/something##
It is not allowed to use only ##"/"## as a source, since it is the parent
for all possible targets.
Note: if used in combination with a ##src_id##, this value is not allowed
to start with ##"/"## either.'
in: query
name: src
required: false
schema:
type: string
- description: 'The "PathID" (##pid##) of the source filesystem object. (Or,
if used in combination with ##src##, its superior directory.)
Example: ##d1372678008.d116##
Note: a ##pid## is not persistent upon changes (rename/move) to a filesystem
object. So after this operation, the ##src_id## may no longer be valid.
However the current value will be part of the returned information (as ##id##)
after a successful request.'
in: query
name: src_id
required: false
schema:
type: string
- description: 'The path to the filesystem object, that shall be the destination
for the operation.
Example: ##/users/example/archive/something##
Note: if used in combination with a ##dst_id##, this value is not allowed
to start with ##"/"##.'
in: query
name: dst
required: true
schema:
type: string
- description: 'If provided, this must always be the ##pid## of a superior directory
of the ##dst##.
Example: d1372678008.d117'
in: query
name: dst_id
required: false
schema:
type: string
- description: 'Optional parameter to determine the API behavior in case of
a conflict with an existing filesystem object.
**Possible value:**
##"autoname" - Find another name if the destination already exists.
"overwrite" - (not for directories) Replace destination object with source.
##
Note: when source and destination are the same, the operation results in
an ##error 409##.'
in: query
name: on_exist
required: false
schema:
type: string
- description: The modification time (mtime) of the source parent folder to
be set after the operation.
in: query
name: src_parent_mtime
required: false
schema:
type: number
- description: The modification time (mtime) of the destination parent folder
to be set after the operation.
in: query
name: dst_parent_mtime
required: false
schema:
type: number
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'409':
description: Conflict
'422':
description: Unprocessable Entity (e.g. name too long)
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Move a file
tags:
- file
/file/rename:
post:
description: 'Rename a file.
Both, the ##pid## and ##path## parameters identify a filesystem object, at
least one of them is always mandatory.
It is allowed to use both together, in which case ##pid## addresses a superior
directory, and the value of ##path## is considered relative to that directory.
(##<pid>/<path>##)'
parameters:
- description: 'The path to a filesystem object.
Example: ##/users/example/Music##
The shortest possible path is ##"/"##, which will always refer to the topmost
directory accessible by the authenticated user. For a regular HiDrive user
this is the HiDrive ##"root"##. If used with a [L[/#cv#/share/token_POST]share
access_token] it will be the shared directory.
Note: if used in combination with a ##pid##, this value is not allowed to
start with ##"/"##.'
in: query
name: path
required: false
schema:
type: string
- description: 'The "PathID" is a path and encoding independant representation
of a specific filesystem object. Also returned and refered to as ##id##
in data related responses.
Example: ##d1372678008.d116##
Note: the ##pid## is not persistent upon changes (rename/move) to a filesystem
object.'
in: query
name: pid
required: false
schema:
type: string
- description: 'New name.
Filename only, without the path.'
in: query
name: name
required: true
schema:
type: string
- description: 'Optional parameter to determine the API behavior in case of
a conflict with an existing filesystem object.
**Possible value:**
##"autoname" - Find another name if the destination already exists.
"overwrite" - (not for directories) Replace destination object with source.
##
Note: when source and destination are the same, the operation results in
an ##error 409##.'
in: query
name: on_exist
required: false
schema:
type: string
- description: The modification time (mtime) of the file system target's parent
folder to be set after the operation.
in: query
name: parent_mtime
required: false
schema:
type: number
responses:
'201':
description: Created
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'409':
description: Conflict
'422':
description: Unprocessable Entity (e.g. name too long)
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Rename a file
tags:
- file
/file/thumbnail:
get:
description: 'Get a thumbnail of a file. Thumbnails are cached and will be created
if they are requested first or the base file has changed. Their Exif information
has been stripped after auto-orienting.
To get a thumbnail of a snapshotted file, the name of the snapshot must be
provided in the snapshot parameter. The name must be UTF-8 encoded.
In some cases, it might be required to pass authentication-data via request
parameter instead of the "Authentication" header (if the environment does
not allow for header-data to be set, as in HTML img-tags). You can use ##access_token=BASE64_access_token##
for those situations. However, if "Authentication" header-data can be set,
it should be the preferred way.'
parameters:
- description: 'The path to a filesystem object.
Example: ##/users/example/Music##
The shortest possible path is ##"/"##, which will always refer to the topmost
directory accessible by the authenticated user. For a regular HiDrive user
this is the HiDrive ##"root"##. If used with a [L[/#cv#/share/token_POST]share
access_token] it will be the shared directory.
Note: if used in combination with a ##pid##, this value is not allowed to
start with ##"/"##.'
in: query
name: path
required: false
schema:
type: string
- description: 'The "PathID" is a path and encoding independant representation
of a specific filesystem object. Also returned and refered to as ##id##
in data related responses.
Example: ##d1372678008.d116##
Note: the ##pid## is not persistent upon changes (rename/move) to a filesystem
object.'
in: query
name: pid
required: false
schema:
type: string
- description: Maximum width of the thumbnail
in: query
name: width
required: false
schema:
type: number
- description: Maximum height of the thumbnail
in: query
name: height
required: false
schema:
type: number
- description: 'Name of an existing snapshot, as returned by [L[/#cv#/snapshot_GET]GET
/#cv#/snapshot].
If provided, the requested ##path## will be looked up inside the referenced
snapshot.'
in: query
name: snapshot
required: false
schema:
type: string
responses:
'200':
content:
application/octet-stream:
schema:
format: binary
type: string
description: OK
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Get a thumbnail of a file
tags:
- file
/file/truncate:
post:
description: 'Truncate a file.
Both, the ##pid## and ##path## parameters identify a filesystem object, at
least one of them is always mandatory.
It is allowed to use both together, in which case ##pid## addresses a superior
directory, and the value of ##path## is considered relative to that directory.
(##<pid>/<path>##)
**Note of caution:**
This call can create so-called **sparse files**. Those may allocate less space
on the file system than their appearent size indicates, since holes betweens
data chunks are "real" holes and not areas of 0-bytes. The thing to consider
is that subsequent data copy actions usually expand sparse data into 0-bytes.
Long story short: Use this method carefully!'
parameters:
- description: 'The path to a filesystem object.
Example: ##/users/example/Music##
The shortest possible path is ##"/"##, which will always refer to the topmost
directory accessible by the authenticated user. For a regular HiDrive user
this is the HiDrive ##"root"##. If used with a [L[/#cv#/share/token_POST]share
access_token] it will be the shared directory.
Note: if used in combination with a ##pid##, this value is not allowed to
start with ##"/"##.'
in: query
name: path
required: false
schema:
type: string
- description: 'The "PathID" is a path and encoding independant representation
of a specific filesystem object. Also returned and refered to as ##id##
in data related responses.
Example: ##d1372678008.d116##
Note: the ##pid## is not persistent upon changes (rename/move) to a filesystem
object.'
in: query
name: pid
required: false
schema:
type: string
- description: 'The new size of the file.
If the given value is smaller than the current filesize, the file is cut
at the ##size## position. If ##size## is greater, the file is extended to
that value.
Example: 49152'
in: query
name: size
required: true
schema:
type: number
- description: The modification time (mtime) of the file system target to be
set after the operation.
in: query
name: mtime
required: false
schema:
type: number
responses:
'201':
description: Created
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Truncate a file
tags:
- file
/file/url:
get:
description: 'Get a download URL for a file.
The URL will be valid for **six hours**. No further authentication will be
required to download the file using this URL.
The main use case for this endpoint is to support applications that need to
pass a link to a file on to some other component, like a media player. These
third-party players will typically not support OAuth2 or even basic auth,
so link-only authentication is required.
It is, however, not reccomended to use this endpoint to realize multiple file
downloads or implement HTML img-tag display of files. Use [L[/#cv#/file_GET]GET
/#cv#/file] for that purpose.
Both, the ##pid## and ##path## parameters identify a filesystem object, at
least one of them is always mandatory.
It is allowed to use both together, in which case ##pid## addresses a superior
directory, and the value of ##path## is considered relative to that directory.
(##<pid>/<path>##)'
parameters:
- description: 'The path to a filesystem object.
Example: ##/users/example/Music##
The shortest possible path is ##"/"##, which will always refer to the topmost
directory accessible by the authenticated user. For a regular HiDrive user
this is the HiDrive ##"root"##. If used with a [L[/#cv#/share/token_POST]share
access_token] it will be the shared directory.
Note: if used in combination with a ##pid##, this value is not allowed to
start with ##"/"##.'
in: query
name: path
required: false
schema:
type: string
- description: 'The "PathID" is a path and encoding independant representation
of a specific filesystem object. Also returned and refered to as ##id##
in data related responses.
Example: ##d1372678008.d116##
Note: the ##pid## is not persistent upon changes (rename/move) to a filesystem
object.'
in: query
name: pid
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Get a download URL for a file
tags:
- file
/fs/copy:
post:
description: 'Copy an arbitrary number of files and directories to a destination
directory.
Both, the ''src_id'' and ''src'' parameters refer to source files or directories,
at least one of them is mandatory. If both are given, only one ''src_id''
parameter, but any number of ''src'' parameters is allowed, ''src_id'' addresses
a superior directory, and the values of ''src'' are relative paths to the
actual source file or directory.
Similarly ''dst_id'' and ''dst'' refer to the destination directory. If ''dst_id''
or ''dst'' is given alone, it addresses the destination directly, otherwise
''dst_id'' refers to a superior directory, and ''dst'' is the relative path
from that directory to the destination directory.
If a snapshot is provided all source data is copied from that snapshot.
If the copies have been processed, the response body contains two arrays under
''done'' and ''failed''. Each path given in parameter ''src'' will have a
result section in one of these arrays.
When all operations succeeded, array ''failed'' will be empty and the HTTP
status code is "200 OK". If all operations failed, then array ''done'' is
empty and ''failed'' contains a list of responses for each of the ''src''
paths, containing the fiels ''code'' (HTTP status), ''msg'' (error message)
and ''src'' and/or ''src_id''. In case all errors share the same status code,
it will be used as the HTTP response for this request. For diverging results,
the HTTP status code is "207 Multi-Status".
An error concerning the destination directory (dst) will result in an error
JSON object with ''code'' and ''msg''.
**A note about sparse files:**
Copying a sparse file does not preserve sparse-ness on the destination: Sparse
areas in the source are expanded to blocks of 0-bytes in the destination.
See notes about sparse files in [L[/#cv#/file_PATCH]PATCH /#cv#/file] and
[L[/#cv#/file/truncate_POST]POST /#cv#/file/truncate].'
parameters:
- description: One or many path names.
in: query
name: src
required: false
schema:
items:
type: string
type: array
- description: One or many path ids.
in: query
name: src_id
required: false
schema:
items:
type: string
type: array
- description: Path to destination directory.
in: query
name: dst
required: false
schema:
type: string
- description: Refers to a directory, which is either the destination directory,
if no "dst" parameter is given, or a superior directory of the destination,
and the value of "dst" is a relative path.
in: query
name: dst_id
required: false
schema:
type: string
- description: 'Possible value:
"autoname" - Find another name if the destination already exists. Should
you copy the root directory ''/'' from a snapshot and subfolders already
exist in the destination, autoname will insert a folder prefixed with ''copy''
into the hierarchy.'
in: query
name: on_exist
required: false
schema:
type: string
- description: 'Name of snapshot. Note: Mutually exclusive with the src id parameter,
since a public id may reference something in a snapshot.'
in: query
name: snapshot
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'207':
description: Multi-Status (body contains multiple statuses).
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (no authentication)
'403':
description: 'Forbidden (e.g. forbidden: acl)'
'404':
description: Not Found (e.g. file/dir not existing)
'409':
description: Conflict (destination file exists)
'422':
description: Unprocessable Entity (e.g. name too long)
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Copy an arbitrary number of files and directories to a destination
directory
tags:
- fs
/fs/delete:
post:
description: 'Delete multiple directories and/or files at once. If the deletes
have been processed, the response body contains two arrays under ''done''
and ''failed''. Each path given in parameter src will have a result section
in one of these arrays.
When all operations succeeded, array ''failed'' will be empty and the HTTP
status code is "200 OK". If all operations failed, then array ''done'' is
empty and ''failed'' contains a list of responses for each of the src paths,
containing the fields ''code'' (HTTP status), ''msg'' (error message) and
''src'' and/or ''src_id''. In case all errors share the same status code,
it will be used as the HTTP response for this request. For diverging results,
the HTTP status code is "207 Multi-Status".
Enforce the HiDrive ACLs but adjusts deviant POSIX ACLs of the src and his
parent when required. This may be necessary if the Permissions have been changed
using protocols like SMB or rsync. The permissions will be restored if the
operation completes successfully. Due to missing transactional semantics the
permissions may not be restored if the operation fails (e.g. with an exception)'
parameters:
- description: One or many path names
in: query
name: path
required: false
schema:
items:
type: string
type: array
- description: One or many path ids.
in: query
name: pid
required: false
schema:
items:
type: string
type: array
- description: 'If set, the call will also delete non-empty directories and
their contents recursively without throwing a ##409 Conflict## error.'
in: query
name: recursive
required: false
schema:
type: boolean
responses:
'200':
content: {}
description: OK
'207':
description: Multi-Status (body contains multiple statuses).
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (no authentication)
'403':
description: 'Forbidden (e.g. forbidden: acl)'
'404':
description: Not Found (e.g. file/dir not existing)
'409':
description: Conflict (delete a non-empty directory without recursive flag)
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Delete multiple directories and/or files at once
tags:
- fs
/fs/move:
post:
description: 'Move one or multiple directories and/or files to a given destination.
Both, the ''src_id'' and ''src'' parameters refer to source files or directories,
at least one of them is mandatory. If both are given, only one ''src_id''
parameter, but any number of ''src'' parameters is allowed, ''src_id'' addresses
a superior directory, and the values of ''src'' are relative paths to the
actual source file of directory.
Similarly ''dst_id'' and ''dst'' refer to the destination directory. If ''dst_id''
or ''dst'' is given alone, it addresses the destination directly, otherwise
''dst_id'' refers to a superior directory, and ''dst'' is the relative path
from that directory to the destination directory.
If the moves have been processed, the response body contains two arrays under
''done'' and ''failed''. Each path given in parameter ''src'' will have a
result section in one of these arrays.
When all operations succeeded, array ''failed'' will be empty and the HTTP
status code is "200 OK". If all operations failed, then array ''done'' is
empty and ''failed'' contains a list of responses for each of the ''src''
paths, containing the fiels ''code'' (HTTP status), ''msg'' (error message)
and ''src'' and/or ''src_id''. In case all errors share the same status code,
it will be used as the HTTP response for this request. For diverging results,
the HTTP status code is "207 Multi-Status".
An error concerning the destination directory (dst) will result in a normal
error JSON object, with ''code'' and ''message''.
As in common file systems, ##move## is a cheap operation if source and destination
are on the same file system. A cross-device move is actually a copy operation
followed by a delete operation on the source object. Please notice [L[/#cv#/fs/copy_POST]the
section about sparse files in copy] in this context.'
parameters:
- description: One or many path names.
in: query
name: src
required: false
schema:
items:
type: string
type: array
- description: One or many path ids.
in: query
name: src_id
required: false
schema:
items:
type: string
type: array
- description: Path to destination directory.
in: query
name: dst
required: false
schema:
type: string
- description: Refers to a directory, which is either the destination directory,
if no 'dst' parameter is given, or a superior directory of the destination,
and the value of 'dst' is a relative path.
in: query
name: dst_id
required: false
schema:
type: string
- description: 'Possible value:
"autoname" - Find another name if the destination already exists. Note:
when source and destination are the same, the operation results in an error
(409)'
in: query
name: on_exist
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'207':
description: Multi-Status (body contains multiple statuses).
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (no authentication)
'403':
description: 'Forbidden (e.g. forbidden: acl)'
'404':
description: Not Found (e.g. file/dir not existing)
'409':
description: Conflict (destination file exists)
'422':
description: Unprocessable Entity (e.g. name too long)
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Move one or multiple directories and/or files to a given destination
tags:
- fs
/git/init:
post:
description: 'Create a Git bare repository with the given path and optional
superior directory id and return data of created directory.
Both, the "pid" and "path" parameters refer to the Git repository, where "path"
is mandatory and "pid" optional. If both are given, "pid" addresses a superior
directory, and the value of "path" is a relative path to that directory.
ATTENTION!!! This will not create missing parent directories - the parent
directory has to exist!'
parameters:
- description: 'Path to the new repository. The name must have the ".git" extension.
Example: /users/foobar/existingDir/repository.git'
in: query
name: path
required: true
schema:
type: string
- description: 'Public id of a superior directory.
Example: d1372678008.d115'
in: query
name: pid
required: false
schema:
type: string
responses:
'201':
description: Created
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (no authentication)
'403':
description: 'Forbidden (e.g. forbidden: acl)'
'404':
description: Not Found (e.g. parent not existing)
'409':
description: Conflict (e.g. directory exists)
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Create a Git bare repository with the given path and optional superior
directory id and return data of created directory
tags:
- git
/mailupload:
delete:
description: 'Remove mailupload from the given directory.
Both, the "pid" and "path" parameters refer to the directory, at least one
of them is mandatory. If both are given, "pid" addresses a superior directory,
and the value of "path" is a relative path to that directory.'
parameters:
- description: 'The public id of the mailupload folder or public id of a superior
directory if "path" is given. The public id can be taken from an "id"-field
of a previous response (if included by default or via the "fields"-parameter).
Example: d1372678008.d116'
in: query
name: pid
required: false
schema:
type: string
- description: Path to a folder
in: query
name: path
required: true
schema:
type: string
responses:
'204':
description: No Content
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (no authentication)
'403':
description: 'Forbidden (Forbidden: Insufficient privileges)'
'404':
description: Not Found (e.g. path not existing/not mailupload path)
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Remove mailupload from the given directory
tags:
- mailupload
get:
description: 'Get information about a particular mailupload or all mailuploads
of the authenticated user.
Both the "pid" and "path" parameters refer to the directory, at least one
of them is mandatory. If both are given, "pid" addresses a superior directory,
and the value of "path" is a relative path to that directory.
Use without param to get a list of all mailupload data set by the authenticated
user.'
parameters:
- description: Path to mailupload folder
in: query
name: path
required: false
schema:
type: string
- description: 'The public id of the mailupload folder or public id of a superior
directory if "path" is given. The public id can be taken from an "id"-field
of a previous response (if included by default or via the "fields"-parameter).
Example: d1372678008.d116'
in: query
name: pid
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (no authentication)
'403':
description: 'Forbidden (Forbidden: Insufficient privileges)'
'404':
description: Not Found (e.g. path not existing)
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Get information about a particular mailupload or all mailuploads of
the authenticated user
tags:
- mailupload
post:
description: 'Create a new mailupload.
Both the "pid" and "path" parameters refer to the directory, at least one
of them is mandatory. If both are given, "pid" addresses a superior directory,
and the value of "path" is a relative path to that directory.
Note that the maximum size for an email is 100MB, this value includes all
headers and the encoded attachment.'
parameters:
- description: Path to a mailupload folder.
in: query
name: path
required: false
schema:
type: string
- description: 'The public id of the mailupload folder or public id of a superior
directory if "path" is given. The public id can be taken from an "id"-field
of a previous response (if included by default or via the "fields"-parameter).
Example: d1372678008.d116'
in: query
name: pid
required: false
schema:
type: string
- description: '"dir"'
in: query
name: type
required: true
schema:
type: string
- description: 'a string ##[a-zA-Z._-]## There are two ways to provide the localpart
for the mailupload address. The first is to provide rcpt_string + optionally
rcpt_secret. This way the resulting email address will be <user alias>+<rcpt_string>+<rcpt_secret>@...,
with literal ''+'' in between.
The other way is to provide a unique identifier retrieved from the /unique-
endpoint. For this, you provide unique and unique_mac instead of rcpt_string
and rcpt_secret.'
in: query
name: rcpt_string
required: false
schema:
type: string
- description: 'An additional part behind rcpt_string. Must be five characters
long and must not contain characters other than ##[a-zA-Z._-]##. See rcpt_string
for more information.'
in: query
name: rcpt_secret
required: false
schema:
type: string
- description: A unique identifier retrieved from the /unique-endpoint. See
rcpt_string for more explanation. If this parameter is given, unique_mac
also has to be provided.
in: query
name: unique
required: false
schema:
type: string
- description: A MAC (Message Authentication Code) that proves that the unique
string is really the result of a unique request.
in: query
name: unique_mac
required: false
schema:
type: string
- description: timestamp of expiration date
in: query
name: ttl
required: false
schema:
$ref: '#/components/schemas/Timestamp'
- description: 'Whether or not overwrite files of the same name inside the target
folder with the new incoming file. A true value enables overwriting wheras
false indicates that incoming files will be renamed to ##file[1].ext## or
##file[2].ext## if the target exists, and if all those files exist nothing
is saved.'
in: query
name: overwrite
required: false
schema:
type: boolean
- description: send report to sender
in: query
name: reportok
required: false
schema:
type: boolean
- description: send report to user (set email)
in: query
name: reportto
required: false
schema:
type: string
- description: create a subfolder for each sender
in: query
name: subfolder
required: false
schema:
type: boolean
responses:
'201':
description: Created
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (no authentication)
'403':
description: 'Forbidden (Forbidden: Insufficient privileges)'
'404':
description: Not Found (e.g. path not existing)
'409':
description: Conflict (e.g. mailupload for this path already set - use PUT)
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Create a new mailupload
tags:
- mailupload
put:
description: 'Update an existing mailupload. You may only use the parameters
you want to change/update.
Both, the "pid" and "path" parameters refer to the directory, at least one
of them is mandatory. If both are given, "pid" addresses a superior directory,
and the value of "path" is a relative path to that directory. Use this to
update mailupload settings for a specified directory.
Note that the maximum size for an email is 100MB, this value includes all
headers and the encoded attachment.'
parameters:
- description: 'The public id of the mailupload folder or public id of a superior
directory if "path" is given. The public id can be taken from an "id"-field
of a previous response (if included by default or via the "fields"-parameter).
Example: d1372678008.d116'
in: query
name: pid
required: false
schema:
type: string
- description: Path to a folder
in: query
name: path
required: true
schema:
type: string
- description: 'a string ##[a-zA-Z._-]##.'
in: query
name: rcpt_string
required: false
schema:
type: string
- description: 'An additional part behind rcpt_string. Must be five characters
long and must not contain characters other than ##[a-zA-Z._-]##.'
in: query
name: rcpt_secret
required: false
schema:
type: string
- description: A unique identifier retrieved from the /unique-endpoint. See
POST for more information.
in: query
name: unique
required: false
schema:
type: string
- description: A MAC (Message Authentication Code) that proves that the unique
string is really the result of a unique request.
in: query
name: unique_mac
required: false
schema:
type: string
- description: timestamp of expiration date
in: query
name: ttl
required: false
schema:
$ref: '#/components/schemas/Timestamp'
- description: 'Whether or not overwrite files of the same name inside the target
folder with the new incoming file. A true value enables overwriting wheras
false indicates that incoming files will be renamed to ##file[1].ext## or
##file[2].ext## if the target exists, and if all those files exist nothing
is saved.'
in: query
name: overwrite
required: false
schema:
type: boolean
- description: send report to sender
in: query
name: reportok
required: false
schema:
type: boolean
- description: send report to user (set email)
in: query
name: reportto
required: false
schema:
type: string
- description: create a subfolder for each sender
in: query
name: subfolder
required: false
schema:
type: boolean
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (no authentication)
'403':
description: 'Forbidden (Forbidden: Insufficient privileges)'
'404':
description: Not Found (e.g. path not existing/not mailupload target)
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Update an existing mailupload
tags:
- mailupload
/mailupload/config:
get:
description: Get config values for mailupload to show in your GUI. At the moment,
only the mailupload domain is returned for which the local part is created
with [L[/#cv#/mailupload_POST]POST /#cv#/mailupload] to generate a valid upload
email address.
parameters: []
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'500':
description: Internal Error
security: []
summary: Get config values for mailupload to show in your GUI
tags:
- mailupload
/meta:
get:
description: 'Get metadata of a storage object (dir, file or symlink). At least
one of the parameters path and pid is mandatory. If both are given, pid must
address a directory, and the value of path is a relative path from that directory.
To get data from a snapshot, the name of the snapshot must be provided in
the snapshot parameter. The name must be UTF-8 encoded.'
parameters:
- description: 'Local path to the object.
Example: root/users/foobar/Music/file.ext'
in: query
name: path
required: false
schema:
type: string
- description: 'The public id of the object; returned as "id" in a previous
response (by default or via "fields"-parameter).
Example: d1372678008.f482'
in: query
name: pid
required: false
schema:
type: string
- description: 'Name of snapshot. Note: Mutually exclusive with the pid parameter,
since a public id may reference something in a snapshot.'
in: query
name: snapshot
required: false
schema:
type: string
- description: 'Comma-separated list of response fields The "fields" parameter
defines which fields will appear in the response. If the fields parameter
is not given, the default is
## ctime,has_dirs,mtime,readable,size,type,writable ## In generall output
key names are those, that are valid for the possible file types - "dir",
"file" and "symlink".
**Information about shared objects**
use fields value "rshare" to get an array containing a full set of share
information objects. ##rshare## Each share-element is guaranteed to contain
a **share_type** attribute, which can be one of "sharelink, sharedir, shareupload,
mailupload". Other attributes may vary depending on the given type (consult
the respective controller documentation for further details on each share
type).
Share-element attributes may not be limited or filtered any further by fields
parameters.
**Information about the zone (filesystem) of a directory**
use fields value "zone" to get a reasonable subset of zone fields ## zone.available,
zone.quota ## Full list:
##zone.available, zone.quota, zone.used
##
**Information about the EXIF data of an image file**
A limited subset of exif data can be obtained with: ## image.exif ##
The following EXIF tags are supported:
##DateTimeOriginal, Make, Model,
ImageWidth, ImageHeight, ExifImageWidth, ExifImageHeight,
Aperture, ExposureTime, ISO, FocalLength, Orientation,
XResolution, YResolution, ResolutionUnit, BitsPerSample,
GPSLatitude, GPSLongitude, GPSAltitude
##
The returned image.exif object may contain only data for some of the tags
or even be completely empty. The values for the tags ImageWidth and ImageHeight
are derived from the image header and should be identical to image.height
and image.width, respectively. The values for ExifImageWidth and ExifImageHeight
are taken from EXIF information and may differ from ImageWidth and ImageHeight,
for example when the image was scaled by a non-EXIF aware application.
Field names, that do not apply are simply ignored.
**Hash Information**
In order to use our synchronization feature, you''ll need to check several
hashes e.g. for file data, meta data etc. Those hashes are represented by
the field values:
##chash, mhash, mohash, nhash
##
Further information on the complete sync system can be found at the dedicated
sync documentation part of our developer page.'
in: query
name: fields
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (no authentication)
'403':
description: 'Forbidden (e.g. forbidden: acl)'
'404':
description: Not Found (e.g. file not existing)
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Get metadata of a storage object (dir, file or symlink)
tags:
- meta
patch:
description: 'Modify meta data of a file or directory.
At the moment ##mtime## is the only attribute that can be changed.'
parameters:
- description: 'Local path to the object.
Example: root/users/foobar/Music/file.ext'
in: query
name: path
required: false
schema:
type: string
- description: 'The public id of the object; returned as "id" in a previous
response (by default or via "fields"-parameter).
Example: d1372678008.f482'
in: query
name: pid
required: false
schema:
type: string
- description: A Unix timestamp ("seconds since the Unix Epoch").
in: query
name: mtime
required: true
schema:
type: number
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (no authentication)
'403':
description: 'Forbidden (e.g. forbidden: acl)'
'404':
description: Not Found (e.g. dir not existing)
'500':
description: Internal Error
'507':
description: Insufficient Storage
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Modify meta data of a file or directory
tags:
- meta
/permission:
get:
description: 'Get access permissions for a file or folder for the authenticated
or a given user account. Does not consider further permission constraints
for the current app.
Permissions are represented by boolean values for the attributes "readable"
and "writable".
Please note that you need admin or owner role to access information for other
user accounts.
This call is not allowed for shared directories.'
parameters:
- description: Path to a folder or file to check ACLs
in: query
name: path
required: true
schema:
type: string
- description: 'The public id of the folder or file; returned as "id" in a previous
response (by default or via "fields"-parameter).
Example: d1372678008.d116'
in: query
name: pid
required: false
schema:
type: string
- description: 'Account id. Example: "54321.1"'
in: query
name: account
required: false
schema:
type: string
- description: 'Comma-separated list of response fields
The "fields" parameter defines which fields will appear in the response.
If the fields parameter is not given, the default is
readable,writable
Additional valid field names are "account" and "path".'
in: query
name: fields
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (no authentication)
'403':
description: 'Forbidden (Forbidden: Insufficient roles)'
'404':
description: Not Found (e.g. account not existing)
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Get access permissions for a file or folder for the authenticated or
a given user account
tags:
- permission
put:
description: 'Set roles of a specific file or folder for the authenticated or
a given user account.
Alternatively permissions can be added to a pending user invitation. When
the invitee accepts the invitation, all collected permissions are tried to
be set. Should the folder be gone by that time, the respective permissions
are ignored.
Permissions are represented by boolean values for the attributes C<readable>
and C<writable>.
Please note that you need admin or owner role to set roles for other user
accounts.
At the moment only root/public is a valid path to set explicit roles.'
parameters:
- description: path to a folder or file to check ACLs
in: query
name: path
required: true
schema:
type: string
- description: 'The public id of the folder or file; returned as "id" in a previous
response (by default or via "fields"-parameter).
Example: d1372678008.d116'
in: query
name: pid
required: false
schema:
type: string
- description: 'accountID. Example: "54321.1". Mutually exclusive with invite_id.'
in: query
name: account
required: false
schema:
type: string
- description: id returned from POST /usr/invite. Mutually exclusive with account_id.
in: query
name: invite_id
required: false
schema:
type: string
- description: set read access
in: query
name: readable
required: false
schema:
type: boolean
- description: set write access
in: query
name: writable
required: false
schema:
type: boolean
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (no authentication)
'403':
description: 'Forbidden (Forbidden: Insufficient roles)'
'404':
description: Not Found (e.g. account not existing)
'500':
description: Internal Error
'504':
description: Gateway Timeout
security:
- BearerAuth: []
- oAuth2:
- owner,rw
- owner,ro
- admin,rw
- admin,ro
summary: Set roles of a specific file or folder for the authenticated or a given
user account
tags:
- permission
/search:
get:
description: 'Search for a specified pattern within all filenames (including
directories and symlinks). The search can be restricted to a subdirectory
by specifying at least one of the parameters path and pid. If both are given,
pid must address a directory, and the value of path is a relative path from
that directory. Althought the pattern has to be given in UTF-8, the search
also tries to match names with different encodings, namely the various ISO
8859-variants. It is possible to give a language as a hint to the search algorithms.
While a search query is running, the API will not accept any other requests.
To abort a running query, the tcp connection can be closed.'
parameters:
- description: 'Local path to the directory in which to start the search.
Example: root/users/foobar/Music/file.ext'
in: query
name: path
required: false
schema:
type: string
- description: 'The public id to the directory in which to start the search;
interpreted in combination with the path-parameter. If neither pid nor path
are given, a default path of "/" is assumed.
Example: d1372678008.f482'
in: query
name: pid
required: false
schema:
type: string
- description: The pattern to search for. A substring-match is performed on
all object names. The paramater has to be given as UTF-8. If the pattern
contains letters with diacritics, the object name has to match those exactly.
On the other hand, base letters in the pattern will also be matched against
those with diacritics. Punctiation marks in the object name are ignored.
in: query
name: pattern
required: false
schema:
type: string
- description: With this parameter it is possible to give a hint to the search
algorithm. The language has to be given either as an ISO 639-1 two-letter
code or as an IETF language tag. If the filename is encoded as valid UTF-8,
the comparison is performed in UTF-8. Otherwise, depending on the given
language, an ISO-8859-variant is assumed as encoding. This parameter defaults
to language defined by the tariff.
in: query
name: language
required: false
schema:
type: string
- description: Limit the number of search results. Defaults to 5000. By giving
this parameter the limit can be raised or lowered.
in: query
name: limit
required: false
schema:
type: number
- description: 'Comma-separated list of response fields The "fields" parameter
defines which fields will appear in the response. See the description of
GET /meta for a list of possible values.
Defaults to id,parent_id,path,ctime,mtime,readable,size,type,writable.'
in: query
name: fields
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (no authentication)
'403':
description: 'Forbidden (e.g. forbidden: acl)'
'404':
description: Not Found (e.g. given pid/path not existing)
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Search for a specified pattern within all filenames (including directories
and symlinks)
tags:
- meta
/share:
delete:
description: Delete a given share, thus invalidating each existing share access_token
immediately.
parameters:
- description: A shareID as returned by [L[/#cv#/share_GET]GET /#cv#/share]
or [L[/#cv#/share_POST]POST /#cv#/share]
in: query
name: id
required: true
schema:
type: string
responses:
'204':
description: No Content
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found (e.g. ID not existing)
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Delete a given share, thus invalidating each existing share access_token
immediately
tags:
- share
get:
description: 'Get information about either one (given "id", "path" or "pid"
parameter) or every existing share created by the authenticated user.
You may customize the resultset by adding optional "fields" values.'
parameters:
- description: A share id as returned by [L[/#cv#/share_GET]GET /#cv#/share]
or [L[/#cv#/share_POST]POST /#cv#/share]
in: query
name: id
required: false
schema:
type: string
- description: Name of a shared path.
in: query
name: path
required: false
schema:
type: string
- description: Id of a shared path.
in: query
name: pid
required: false
schema:
type: string
- description: 'available fields:
##count - int - the number of successfully completed downloads
created - int - UNIX timestamp
file_type - string - ''dir''
has_password - bool
is_encrypted - bool - is the given share encrypted
id - string - the unique share id
last_modified - int - UNIX timestamp
maxcount (*) - int - maximum number of share-tokens
name - int - name of the shared directory
password (*) - string - optional password for the share
path - string - path of the shared directory
pid - string - path id of the shared directory
readable - bool
remaining - int - number of remaining available share tokens
share_type - string - ''sharedir''
size - int - size of the shared directory
status - string - ''valid'', ''invalid'' or ''expired''
ttl - int - time-to-live, in seconds, possibly negative
uri - string - url of the shared directory
valid_until - int - UNIX timestamp
writable - bool
##
c&p friendly: ## count,created,file_type,has_password,is_encrypted,id,last_modified,maxcount,name,password,path,pid,readable,remaining,share_type,size,status,ttl,uri,valid_until,writable
##
default: ##file_type, id, path, status, uri##
**Note:** that fields marked with ##(*)## are only included if they are
set.'
in: query
name: fields
required: false
schema:
type: string
responses:
'200':
content: {}
description: OK
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (password required)
'403':
description: Forbidden (wrong password)
'404':
description: Not Found (ID does not exist or given path is not shared).
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Get information about either one (given "id", "path" or "pid" parameter)
or every existing share created by the authenticated user
tags:
- share
post:
description: 'Create a new share for a given directory anywhere inside your
accessible HiDrive.
You may limit the validity of a share to a given amount of time and protect
it with a password.
Sharing a directory will allow anyone with knowledge of the specific (returned)
share_id to access **all** data inside that directory and **all** its children
(read-only).
For ease of access, HiDrive also provides a share-gui to access the shared
files comfortably. The so called "share_url" will be returned as well.
However, if you wish to implement an individual share-access solution, you
may do so utilizing the [L[/#cv#/share/token_POST]POST /#cv#/share/token]
endpoint.'
parameters:
- description: 'Number of share tokens that can be issued for this share.
When not provided, the value will be set to unlimited, if the user''s tariff
supports it, otherwise to the maximium value permissible. See [L[/#cv#/features_GET]GET
/#cv#/features] for tariff specific details.'
in: query
name: maxcount
required: false
schema:
type: number
- description: 'Local path to the directory.
Example: root/users/foobar/Music'
in: query
name: path
required: false
schema:
type: string
- description: 'The public id of the directory; returned as "id" in a previous
response (by default or via "fields"-parameter).
Example: d1372678008.d116'
in: query
name: pid
required: false
schema:
type: string
- description: 'Optional protection for the share. Consider this recommended,
especially the closer the share is set to the root directory.
This parameter must be ommitted for encrypted shares which require salt,
share_access_key, pw_sharekey.'
in: query
name: password
required: false
schema:
type: string
- description: 'This option can be set to allow write access to the shared filesystem
object.
Note: This includes deletion and modification of existing content.'
in: query
name: writable
required: false
schema:
type: boolean
- description: Share expiry. A positive number defining seconds from now. Not
specifying a value sets ttl to the tariff maximum.
in: query
name: ttl
required: false
schema:
type: number
- description: 'Random salt value generated by the hdcrypt library for encrypted
shares. If this parameter is present, the share is created as ''encrypted''
and share_access_key as well as pw_sharekey must also be present. The password
paramter must be ommitted because encrypted shares rely on a challenge-response
authentication that only reqires knowledge of the share_access_key.
Notice: this attribute cannot be removed from a share.'
in: query
name: salt
required: false
schema:
type: string
- description: Authentication key provided by the hdcrypt library for encrypted
shares. Requires password to be absent and salt and pw_sharekey to be present.
in: query
name: share_access_key
required: false
schema:
type: string
- description: Password protected Share Key provided by the hdcrypt library
for encrypted shares. Requires password to be absent and salt and share_access_key
to be present.
in: query
name: pw_sharekey
required: false
schema:
type: string
responses:
'201':
description: Created
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (no authentication)
'403':
description: Forbidden (wrong password)
'404':
description: Not Found (e.g. ID not existing)
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Create a new share for a given directory anywhere inside your accessible
HiDrive
tags:
- share
put:
description: 'Update a given share. Change time-to-live, maxcount and add or
remove a share password.
**Note: ** It is not possible to change the target directory of an existing
share! Please create a new one, if you wish to share another directory.'
parameters:
- description: A share id as returned by [L[/#cv#/share_GET]GET /#cv#/share]
or [L[/#cv#/share_POST]POST /#cv#/share]
in: query
name: id
required: true
schema:
type: string
- description: 'Update the number of share tokens that can be issued for this
share.
The new value cannot be set lower than the current count. If the user''s
tariff supports it, providing an empty value resets the maxcount to unlimited,
otherwise the maximum value depends on the user''s tariff. See [L[/#cv#/features_GET]GET
/#cv#/features] for tariff specific details.'
in: query
name: maxcount
required: false
schema:
type: number
- description: 'Optional protection for the share. Consider this recommended,
especially the closer the share is set to the root directory.
This parameter must be ommitted for encrypted shares which require salt,
share_access_key, pw_sharekey.'
in: query
name: password
required: false
schema:
type: string
- description: 'This option can be set to allow write access to the shared filesystem
object.
Note: This includes deletion and modification of existing content.'
in: query
name: writable
required: false
schema:
type: boolean
- description: Share expiry. A positive number defining seconds from now. Providing
the ttl parameter with an empty value sets ttl to the tariff maximum.
in: query
name: ttl
required: false
schema:
type: number
- description: Random salt value generated by the hdcrypt library for encrypted
shares. This parameter can only be set if the share was created as 'encrypted'.
In this case share_access_key and pw_sharekey must also be present. The
password paramter must be ommitted because encrypted shares rely on a challenge-response
authentication that only reqires knowledge of the share_access_key.
in: query
name: salt
required: false
schema:
type: string
- description: Authentication key provided by the hdcrypt library for encrypted
shares. Requires password to be absent and salt and pw_sharekey to be present.
in: query
name: share_access_key
required: false
schema:
type: string
- description: Password protected Share Key provided by the hdcrypt library
for encrypted shares. Requires password to be absent and salt and share_access_key
to be present.
in: query
name: pw_sharekey
required: false
schema:
type: string
responses:
'200':
content: {}
description: OK
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (password required)
'403':
description: Forbidden (wrong password)
'404':
description: Not Found (e.g. ID not existing)
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Update a given share
tags:
- share
/share/external:
delete:
description: "Delete external share or sharelink. External share is the place\
\ to save share ids and sharelink ids from other HiDrive users. This can be\
\ used to automate access and usage of data from a number of shared sources.\
\ External shares are identified by id and type. Currently the following information\
\ is associated with an external share:\n##id - string -\
\ the id of the sharelink or sharedir\nlabel - string - a label\
\ you attach to the id\npassword - string - the password, that\
\ has been set for the external\n share\nhas_password\
\ - bool - whether the underlying share expects a password\ntype\
\ - string - whether it is a sharelink or a sharedir\nstatus\
\ - string - the status of the share:\n \
\ valid: the share is valid\n expired:\
\ the share is not accessible anymore,\n \
\ because the share was only valid for\n \
\ a certain time period or because it was\n \
\ accessed more often than configured\n \
\ invalid: the share is not accessible anymore,\n \
\ because the directory/file does not\n \
\ exist\n \
\ gone: the share has been deleted\nwritable - bool - whether\
\ the given share is writable\ncreated - int - the creation\
\ time of the external share as a Unix\n timestamp\n\
##\n"
parameters:
- description: A share id as returned by [L[/#cv#/share_GET]GET /#cv#/share]
or [L[/#cv#/share_POST]POST /#cv#/share]
in: query
name: id
required: true
schema:
type: string
- description: Whether you want to delete a "sharedir" or a "sharelink"
in: query
name: type
required: true
schema:
type: string
responses:
'204':
description: No Content
'401':
description: Unauthorized
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Delete external share or sharelink
tags:
- share
get:
description: "List external shares and sharelinks. External share is the place\
\ to save share ids and sharelink ids from other HiDrive users. This can be\
\ used to automate access and usage of data from a number of shared sources.\
\ External shares are identified by id and type. Currently the following information\
\ is associated with an external share:\n##id - string -\
\ the id of the sharelink or sharedir\nlabel - string - a label\
\ you attach to the id\npassword - string - the password, that\
\ has been set for the external\n share\nhas_password\
\ - bool - whether the underlying share expects a password\ntype\
\ - string - whether it is a sharelink or a sharedir\nstatus\
\ - string - the status of the share:\n \
\ valid: the share is valid\n expired:\
\ the share is not accessible anymore,\n \
\ because the share was only valid for\n \
\ a certain time period or because it was\n \
\ accessed more often than configured\n \
\ invalid: the share is not accessible anymore,\n \
\ because the directory/file does not\n \
\ exist\n \
\ gone: the share has been deleted\nwritable - bool - whether\
\ the given share is writable\ncreated - int - the creation\
\ time of the external share as a Unix\n timestamp\n\
##\n"
parameters: []
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'401':
description: Unauthorized
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: List external shares and sharelinks
tags:
- share
post:
description: "Add external share or sharelink. External share is the place to\
\ save share ids and sharelink ids from other HiDrive users. This can be used\
\ to automate access and usage of data from a number of shared sources. External\
\ shares are identified by id and type. Currently the following information\
\ is associated with an external share:\n##id - string -\
\ the id of the sharelink or sharedir\nlabel - string - a label\
\ you attach to the id\npassword - string - the password, that\
\ has been set for the external\n share\nhas_password\
\ - bool - whether the underlying share expects a password\ntype\
\ - string - whether it is a sharelink or a sharedir\nstatus\
\ - string - the status of the share:\n \
\ valid: the share is valid\n expired:\
\ the share is not accessible anymore,\n \
\ because the share was only valid for\n \
\ a certain time period or because it was\n \
\ accessed more often than configured\n \
\ invalid: the share is not accessible anymore,\n \
\ because the directory/file does not\n \
\ exist\n \
\ gone: the share has been deleted\nwritable - bool - whether\
\ the given share is writable\ncreated - int - the creation\
\ time of the external share as a Unix\n timestamp\n\
##\n"
parameters:
- description: A share id as returned by [L[/#cv#/share_GET]GET /#cv#/share]
or [L[/#cv#/share_POST]POST /#cv#/share]
in: query
name: id
required: true
schema:
type: string
- description: A label for an external share/sharelink. The character limit
is 255. The default is the name of the directory/file. The label will be
URL-encoded in the response.
in: query
name: label
required: false
schema:
type: string
- description: The password to access the share/sharelink
in: query
name: password
required: false
schema:
type: string
- description: Whether you want to save a "sharedir" or a "sharelink"
in: query
name: type
required: true
schema:
type: string
responses:
'201':
description: Created
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized
'404':
description: Not Found (id does not exist)
'409':
description: Conflict (e.g. share already added)
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Add external share or sharelink
tags:
- share
put:
description: "Modify external share or sharelink. External share is the place\
\ to save share ids and sharelink ids from other HiDrive users. This can be\
\ used to automate access and usage of data from a number of shared sources.\
\ External shares are identified by id and type. Currently the following information\
\ is associated with an external share:\n##id - string -\
\ the id of the sharelink or sharedir\nlabel - string - a label\
\ you attach to the id\npassword - string - the password, that\
\ has been set for the external\n share\nhas_password\
\ - bool - whether the underlying share expects a password\ntype\
\ - string - whether it is a sharelink or a sharedir\nstatus\
\ - string - the status of the share:\n \
\ valid: the share is valid\n expired:\
\ the share is not accessible anymore,\n \
\ because the share was only valid for\n \
\ a certain time period or because it was\n \
\ accessed more often than configured\n \
\ invalid: the share is not accessible anymore,\n \
\ because the directory/file does not\n \
\ exist\n \
\ gone: the share has been deleted\nwritable - bool - whether\
\ the given share is writable\ncreated - int - the creation\
\ time of the external share as a Unix\n timestamp\n\
##\n"
parameters:
- description: A share id as returned by [L[/#cv#/share_GET]GET /#cv#/share]
or [L[/#cv#/share_POST]POST /#cv#/share]
in: query
name: id
required: true
schema:
type: string
- description: A label for an external share/sharelink. The character limit
is 255. The default is the name of the directory/file. The label will be
URL-encoded in the response.
in: query
name: label
required: false
schema:
type: string
- description: Update the password of the share/sharelink. Pass an empty password
to indicate that no password is necessary.
in: query
name: password
required: false
schema:
type: string
- description: Type of the external share you want to update. Pass "sharedir"
or "sharelink".
in: query
name: type
required: true
schema:
type: string
responses:
'201':
description: Created
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized
'404':
description: Not Found (id does not exist)
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Modify external share or sharelink
tags:
- share
/share/info:
get:
description: Returns basic information on a given share.
parameters:
- description: A shareID as returned by [L[/#cv#/share_GET]GET /#cv#/share]
or [L[/#cv#/share_POST]POST /#cv#/share]
in: query
name: id
required: true
schema:
type: string
responses:
'200':
content: {}
description: OK
'400':
description: Bad Request (e.g. invalid parameter)
'404':
description: Not Found (e.g. ID not existing)
'410':
description: Gone (e.g. share expired)
'500':
description: Internal Error
security: []
summary: Returns basic information on a given share
tags:
- share
/share/invite:
post:
description: Invite other people to a share via e-mail (if supported)
parameters:
- description: A shareID as returned by [L[/#cv#/share_GET]GET /#cv#/share]
or [L[/#cv#/share_POST]POST /#cv#/share]
in: query
name: id
required: true
schema:
type: string
- description: 'A RFC822-compliant, UTF-8 encoded e-mail address. The parameter
can be specified multiple times to send an invite to more than one recipient
at once. ##Note:## If the address is preceded by a string (e.g. "Bob Test"
<[email protected]>), the specified string is used as salutation in the generated
mail without modification. It is recommended to specify names as "Firstname
Lastname" instead of "Lastname, Firstname".'
in: query
name: recipient
required: true
schema:
type: string
- description: A UTF-8 encoded message text that will be included in the e-mail.
in: query
name: msg
required: false
schema:
type: string
- description: A two-letter code for the language you want the invite mail to
be sent in.
in: query
name: lang
required: false
schema:
type: string
responses:
'200':
content: {}
description: OK
'207':
description: Multi-Status (body contains multiple status messages)
'400':
description: Bad Request
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found
'410':
description: Gone
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Invite other people to a share via e-mail (if supported)
tags:
- share
/share/token:
delete:
description: 'Delete the currently used (via "Authorization" header) share access_token.
Return value 204 verifies the successful deletion.
The endpoint may be used to create some sort of "logout" functionality for
shares. This is suggested in case of password protected shares, to allow for
premature invalidation of a given share access by the authorized user. (Default
expiry: 4h)
**Usage**
For simplicity, usage examples are written for cURL to demonstrate the basic
requests and concept of share usage.
Delete an access_token:
##t=`echo -n ''L2oJ32O84QhWdKhk1Jv8'' | base64`; \
curl -H "Authorization: Bearer $t" -X DELETE https://[API]/#cv#/share/token
##'
parameters: []
responses:
'204':
description: No Content (Deleted)
'400':
description: Bad Request (e.g. invalid parameter)
'404':
description: Not Found (e.g. token not existing)
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- user,rw
- user,ro
summary: Delete the currently used (via "Authorization" header) share access_token
tags:
- share
post:
description: "Generate an OAuth2 access_token specifically for the given share.\
\ You may use this access_token to authorize and run API-calls within the\
\ following limitations:\n\n**Restrictions**\n- Only \"Filesystem Access\"\
\ app-permission -> endpoints like [L[/#cv#/dir]/#cv#/dir], [L[/#cv#/file]/#cv#/file],\
\ [L[/#cv#/meta]/#cv#/meta], ...\n- Read-only access\n- 4h lifetime\n\n\n\
**Usage**\nFor simplicity, usage examples are written for cURL to demonstrate\
\ the basic requests and concept of share usage.\n\nStep 1 - Get an access_token:\n\
##curl \\\n -X POST \\\n -d \"id=[shareid]\" \\\n \"https://[API]/#cv#/share/token\"\
\n##\nReturns:\n##{\n \"expires_in\":14400,\n \"access_token\":\"L2oJ32O84QhWdKhk1Jv8\"\
,\n \"token_type\":\"Bearer\"\n}\n##\n\n\nStep 2 - use access_token to\
\ get shared contents:\n##t=`echo -n 'L2oJ32O84QhWdKhk1Jv8' | base64`; \\\n\
\ curl \\\n -H \"Authorization: Bearer $t\" \\\n -X GET \\\n -d\
\ \"path=/\" \\\n https://[API]/#cv#/dir\n##\nStep 3 - use access_token\
\ and content-data (e.g. pid) to download data:\n##t=`echo -n 'L2oJ32O84QhWdKhk1Jv8'\
\ | base64`; \\\n curl \\\n -H \"Authorization: Bearer $t\" \\\n \
\ -X GET \\\n -d \"pid=d3.f1234\" \\\n https://[API]/#cv#/file\n##\n\
\nNotice:\nFor API version 2.1 and below the path format might be different\
\ between accessing a HiDrive file system with user credentials and with a\
\ share access token.\n\nExamples for the behaviour of API version <= 2.1:\n\
\n\n##Access with user access token:\n\n\nRequest: GET /dir?path=root/users/johndoe/dir\n\
Response: all paths start with \"root/users/johndoe/dir\"\n\n\nRequest: GET\
\ /dir?path=/users/johndoe/dir\nResponse: all paths start with \"/users/johndoe/dir\"\
\n\n\nRequest: GET /dir?pid=d1372678008.d4\nResponse: all paths start with\
\ \"root/users/johndoe/dir\"\n\n\nAccess with share access token, share root\
\ = \"root/users/johndoe\":\n\n\n# access root/users/johndoe\nRequest: GET\
\ /dir?path=/\nResponse: all paths start with \"/\"\n\n\nRequest: GET /dir?pid=d1372678008.d4\n\
Response: all paths start with \"/\"\n\n\n# access root/users/johndoe/dir\n\
Request: GET /dir?path=/dir\nResponse: all paths start with \"/dir\"\n\n\n\
Request: GET /dir?pid=d1372678008.d23\nResponse: all paths start with \"\
/dir\"\n##\n\n\nBackground information:\nFor an authenticated HiDrive user\
\ all paths start with \"root/\". Requests with paths of the form \"root/users\"\
\ or with an id will result in responses with paths of the same format.\n\
A valid alias for \"root/something\" is \"/something\", and paths in the response\
\ will be of the same format.\n\nThe root of a share directory can begin anywhere\
\ in a real HiDrive user's directory tree. Therefore when using a share token\
\ to access a HiDrive the shortest path - the path to the root directory\
\ - is \"/\", and all sub directories begin with a slash (\"/\"), in both,\
\ requests and responses.\n\nThis behaviour is somewhat inconsistent, but\
\ exists for backwards compatibility. Be prepared that this might be brought\
\ into line in a future version of the HiDrive API.\n\nFinal Step - [L[/#cv#/share/token_DELETE]DELETE\
\ /#cv#/share/token] (log-out of share)\n\n**encrypted shares**\nThe HiDrive\
\ encryption library (see [L[https://dev.strato.com/hidrive/content.php?r=151-HiDrive-Encryption]documentation]\
\ for further details) allows for encrypted folders to be shared. This creates\
\ three values ##salt##, ##share_access_key## and ##pw_sharekey## which may\
\ be added to a share dataset.\nIn case of an encrypted share, a ##resp##\
\ parameter must be passed. This is calculated by the hdcrypt library as a\
\ response to the ##salt## received from GET /share/info. The original ##pw_sharekey##\
\ will be provided with the token response."
parameters:
- description: A shareID as returned by [L[/#cv#/share_GET]GET /#cv#/share]
or [L[/#cv#/share_POST]POST /#cv#/share]
in: query
name: id
required: true
schema:
type: string
- description: A share-password if set by share-creator.
in: query
name: password
required: false
schema:
type: string
- description: 'The response to the ##salt## value from GET /share/info for
encrypted shares.'
in: query
name: resp
required: false
schema:
type: string
responses:
'200':
content: {}
description: OK
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (password required)
'403':
description: Forbidden (wrong password)
'404':
description: Not Found (e.g. ID not existing)
'410':
description: Gone (e.g. share expired)
'500':
description: Internal Error
security: []
summary: Generate an OAuth2 access_token specifically for the given share
tags:
- share
/sharelink:
delete:
description: Remove sharelink
parameters:
- description: ID of the sharelink to delete
in: query
name: id
required: true
schema:
type: string
responses:
'204':
description: No Content
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (no authentication)
'403':
description: 'Forbidden (Forbidden: Insufficient privileges)'
'404':
description: Not Found (e.g. ID not existing)
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Remove sharelink
tags:
- share
get:
description: If no "id" parameter is given, a **list** of all sharelink objects
of the user is returned. With a given "id" only the corresponding sharelink
**object** is returned, if that exists.
parameters:
- description: ID of a specific sharelink
in: query
name: id
required: false
schema:
type: string
- description: 'Comma-separated list of response fields
The "fields" parameter defines which fields will appear in the response.
If the fields parameter is not given, the default is
id,path,pid,status,type,uri
for the list of sharelink objects, and
status,path,pid,type,uri
for a distinct sharelink object.
**valid values are**
##count - int - the number of successfully completed downloads
created, - int - UNIX time stamp
has_password - bool
id - string - the unique sharelink id
image.exif - object - selected exif data of shared images
image.height - int - height of shared images
image.width - int - width of shared images
last_modified - int - UNIX timestamp
maxcount - int - the maximum number of downloads
name - string - the name of the linked file
path - string - the path of the linked file
password - string - the plaintext password of a private sharelink
pid - string - the public id of the linked file
readable - bool
remaining - int - number of remaining downloads
share_type - string - ''sharelink''
size - int - the size of the linked file
status - string - ''valid'', ''invalid'' or ''expired''
type - string - ''file''
ttl - int - time-to-live, in seconds, negative for expired
sharelinks
uri - string - the download uri for a valid sharelink
writable - bool
##
c&p friendly: ## count,created,has_password,id,image.exif,image.height,image.width,last_modified,maxcount,name,path,pid,readable,remaining,share_type,size,status,type,ttl,uri,writable
##'
in: query
name: fields
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (no authentication)
'403':
description: 'Forbidden (Forbidden: Insufficient privileges)'
'404':
description: Not Found (e.g. ID not existing)
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: If no "id" parameter is given, a **list** of all sharelink objects
of the user is returned
tags:
- share
post:
description: 'Create a new sharelink for a given file.
Both, the "pid" and "path" parameters refer to the file, at least one of them
is mandatory. If both are given, "pid" addresses a superior directory, and
the value of "path" is a relative path to the actual file.
Specific values might be limited by package-feature settings: Parameters **ttl**
and **maxcount** are required, if the tariff defines a maximum limit for these
values. The **password** protection feature is not available in all tariffs.'
parameters:
- description: 'Path to the linked file.
Example: root/users/foobar/mySharefile.ext'
in: query
name: path
required: false
schema:
type: string
- description: 'The public id of the file to be shared or public id of a superior
directory if "path" is given. The public id can be taken from an "id"-field
of a previous response (if included by default or via the "fields"-parameter).
Example: "d1372678008.f116"'
in: query
name: pid
required: false
schema:
type: string
- description: '"file"'
in: query
name: type
required: true
schema:
type: string
- description: Sharelink expiry. A positive number defining seconds from now.
Not specifying a value sets ttl to the tariff maximum.
in: query
name: ttl
required: false
schema:
type: number
- description: 'Total number of allowed successful downloads.
Not specifying a value sets maxcount to the tariff maximum.'
in: query
name: maxcount
required: false
schema:
type: number
- description: 'A password for a "private" sharelink.
Creation of private sharelinks is not possible for some package-feature
settings.'
in: query
name: password
required: false
schema:
type: string
responses:
'201':
description: Created
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (no authentication)
'403':
description: 'Forbidden (Forbidden: Insufficient privileges)'
'404':
description: Not Found (e.g. file not existing)
'409':
description: Conflict (e.g. sharelink for this file already exists - use
PUT)
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Create a new sharelink for a given file
tags:
- share
put:
description: 'Update values for a given sharelink (not available for all tariffs).
Specific values might be limited due to package-feature settings:
The **password** protection feature is not available in all tariffs.
Parameters **ttl** and **maxcount** are required, if the tariff defines a
maximum limit for these values.
The new value for **maxcount** must be equal to greater than the current **count**
and the difference between the value of the current **maxcount** and the new
**maxcount** may be limited, depending on the tariff.
Use GET /features to fetch information about feature limitations.'
parameters:
- description: ID of the sharelink to modify
in: query
name: id
required: true
schema:
type: string
- description: Sharelink expiry. A positive number defining seconds from now.
Providing the ttl parameter with an empty value sets ttl to the tariff maximum.
in: query
name: ttl
required: false
schema:
type: number
- description: 'Update the number of allowed uploads including the current **count**.
An empty value increases maxcount by the tariffs maximum. The new value
cannot be set lower than the current **count**.'
in: query
name: maxcount
required: false
schema:
type: number
- description: 'A password for a "private" sharelink.
Creation of private sharelinks is not possible for some package-feature
settings.'
in: query
name: password
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (no authentication)
'403':
description: 'Forbidden (Forbidden: Insufficient privileges)'
'404':
description: Not Found (e.g. ID not existing)
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Update values for a given sharelink (not available for all tariffs)
tags:
- share
/sharelink/download:
get:
description: 'Get file content.
Serves the requested file as is. The response header line _Content-Type_ is
set appropriatly, if the file''s MIME type is known, otherwise it contains
_application/octet-stream_. Note that requested data will be served in full
as conditional requests using If-Modified-Since and/or Range Headers are **NOT**
supported.
**This method is the only possibility to download sharelink files protected
by password via GET.**'
parameters:
- description: ID of a specific sharelink
in: query
name: id
required: true
schema:
type: string
- description: Requested one time download code (see [L[/#cv#/sharelink/info_POST]
POST /#cv#/sharelink/info]). The code will be invalid after the download
succeeded.
in: query
name: download_code
required: false
schema:
type: string
responses:
'200':
content:
application/octet-stream:
schema:
format: binary
type: string
description: OK
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found (e.g. sharelink does not exist)
'410':
description: Gone (e.g. sharelink expired)
'500':
description: Internal Error
security: []
summary: Get file content
tags:
- share
post:
description: 'Get file content.
Serves the requested file as is. The response header line _Content-Type_ is
set appropriatly, if the file''s MIME type is known, otherwise it contains
_application/octet-stream_. Note that requested data will be served in full
as conditional requests using If-Modified-Since and/or Range Headers are **NOT**
supported.'
parameters:
- description: ID of a specific sharelink
in: query
name: id
required: true
schema:
type: string
- description: Download password for the referenced sharelink. Required when
set by the sharelink's creator.
in: query
name: password
required: false
schema:
type: string
responses:
'200':
content:
application/octet-stream:
schema:
format: binary
type: string
description: OK
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not Found (e.g. sharelink does not exist)
'410':
description: Gone (e.g. sharelink expired)
'500':
description: Internal Error
security: []
summary: Get file content
tags:
- share
/sharelink/download/home:
post:
description: Store data from a sharelink referenced by its public "id" in the
authenticated user's HiDrive home directory. The filename will be determined
from the sharelink information. If a file with that name already exists, it
will be autonamed. For files larger than 1GB, the copy operation will be started
in the background.
parameters:
- description: ID of a specific sharelink
in: query
name: id
required: true
schema:
type: string
- description: Download password for the referenced sharelink. Required when
set by the sharelink's creator.
in: query
name: password
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request (e.g. invalid parameter)
'403':
description: Forbidden
'404':
description: Not Found (e.g. sharelink does not exist)
'410':
description: Gone (e.g. sharelink expired)
'500':
description: Internal Error
'507':
description: Insufficient Storage (e.g. not enough free space in zone)
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Store data from a sharelink referenced by its public "id" in the authenticated
user's HiDrive home directory
tags:
- share
/sharelink/info:
get:
description: Fetch information about a sharelink referenced by its public "id".
parameters:
- description: ID of a specific sharelink
in: query
name: id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request (e.g. invalid parameter)
'403':
description: Forbidden
'404':
description: Not Found (e.g. sharelink does not exist)
'410':
description: Gone (e.g. sharelink expired)
'500':
description: Internal Error
security: []
summary: Fetch information about a sharelink referenced by its public "id"
tags:
- share
post:
description: Fetch information about a sharelink referenced by its public "id".
parameters:
- description: ID of a specific sharelink
in: query
name: id
required: true
schema:
type: string
- description: Sharelink password, required if sharelink is protected by a password.
in: query
name: password
required: false
schema:
type: string
- description: 'Comma-separated list of response fields, that defines which
fields to appear in the response.
c&p friendly:
##download_code,has_password,id,name,remaining,size,status,ttl,type,uri,mime_type
##
'
in: query
name: fields
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request (e.g. invalid parameter)
'403':
description: Forbidden
'404':
description: Not Found (e.g. sharelink does not exist)
'410':
description: Gone (e.g. sharelink expired)
'500':
description: Internal Error
security: []
summary: Fetch information about a sharelink referenced by its public "id"
tags:
- share
/shareupload:
delete:
description: Remove shareupload
parameters:
- description: ID of the shareupload to delete
in: query
name: id
required: true
schema:
type: string
responses:
'204':
description: No Content
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (no authentication)
'403':
description: 'Forbidden (Forbidden: Insufficient privileges)'
'404':
description: Not Found (e.g. ID not existing)
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Remove shareupload
tags:
- share
get:
description: If no "id" parameter is given, a **list** of all shareupload objects
of the user is returned. With a given "id" only the corresponding shareupload
**object** is returned, if that exists.
parameters:
- description: ID of the shareupload
in: query
name: id
required: false
schema:
type: string
- description: 'Comma-separated list of response fields The parameter defines
which fields will appear in the response. If the fields parameter is not
given, the default is
id,path,status,type,uri
for the list of shareupload objects, and
status,path,type,uri
for a distinct shareupload object.'
in: query
name: fields
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (no authentication)
'403':
description: 'Forbidden (Forbidden: Insufficient privileges)'
'404':
description: Not Found (e.g. path not existing)
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: If no "id" parameter is given, a **list** of all shareupload objects
of the user is returned
tags:
- share
post:
description: 'Create a new shareupload for a given directory.
Both, the "pid" and "path" parameters refer to the file, at least one of them
is mandatory. If both are given, "pid" addresses a superior directory, and
the value of "path" is a relative path to the actual file.
Keep in mind, that specific values might be limited by package-feature settings:
Parameters **ttl** and **maxcount** become required, if the tariff defines
a maximum limits for these values. **password** is not available in all tariffs.'
parameters:
- description: Path of the of linked directory.
in: query
name: path
required: false
schema:
type: string
- description: 'The public id of the directory to be shared or public id of
a superior directory if "path" is given. The public id can be taken from
an "id"-field of a previous response (if included by default or via the
"fields"-parameter).
Example: "d1372678008.d116"'
in: query
name: pid
required: false
schema:
type: string
- description: '"dir"'
in: query
name: type
required: true
schema:
type: string
- description: Shareupload expiry. A positive number defining seconds from now.
Not specifying a value sets ttl to the tariff maximum.
in: query
name: ttl
required: false
schema:
type: number
- description: Number of allowed uploads. Not specifying a value sets maxcount
to the tariff maximum.
in: query
name: maxcount
required: false
schema:
type: number
- description: Maximum upload file-size in bytes. An empty or unset value sets
maxsize to the actual upload maximum, which is 2^31-1 (= 2147483647) bytes.
in: query
name: maxsize
required: false
schema:
type: number
- description: A password for a "private" shareupload.
in: query
name: password
required: false
schema:
type: string
responses:
'201':
description: Created
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (no authentication)
'403':
description: 'Forbidden (Forbidden: Insufficient privileges)'
'404':
description: Not Found (e.g. path not existing)
'409':
description: Conflict (e.g. shareupload for this path already set - use
PUT)
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Create a new shareupload for a given directory
tags:
- share
put:
description: 'Update values for a given shareupload.
If an (optional) parameter is not given, the current value is not touched.
To remove a shareupload setting, the corresponding parameter must be set,
but empty.
Keep in mind, that specific values might be limited by package-feature settings.
For example if it''s allowed to add a password or the maximum amount of downloads
you can configure.
The use of this function itself might be prohibited by package-settings.
Use GET /feature to get information about feature limitations.'
parameters:
- description: The shareupload id.
in: query
name: id
required: true
schema:
type: string
- description: Shareupload expiry. A positive number defining seconds from now.
Providing the ttl parameter with an empty value sets ttl to the tariff maximum.
in: query
name: ttl
required: false
schema:
type: number
- description: 'Update the number of allowed uploads including the current **count**.
An empty value increases maxcount by the tariffs maximum. The new value
cannot be set lower than the current **count**.'
in: query
name: maxcount
required: false
schema:
type: number
- description: Maximum upload file-size in bytes.
in: query
name: maxsize
required: false
schema:
type: number
- description: A password for a "private" shareupload. An empty value sets maxsize
to the actual upload maximum, which is 2^31-1 (= 2147483647) bytes.
in: query
name: password
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (no authentication)
'403':
description: 'Forbidden (Forbidden: Insufficient privileges)'
'404':
description: Not Found (e.g. path not existing)
'409':
description: Conflict (e.g. shareupload for this path already set - use
PUT)
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Update values for a given shareupload
tags:
- share
/shareupload/info:
get:
description: This shareupload referenced by its public "id".
parameters:
- description: ID of a specific shareupload
in: query
name: id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request (e.g. invalid parameter)
'403':
description: Forbidden
'404':
description: Not Found (e.g. shareupload does not exist)
'410':
description: Gone (e.g. shareupload expired)
'500':
description: Internal Error
security: []
summary: This shareupload referenced by its public "id"
tags:
- share
post:
description: 'Fetch information about a shareupload referenced by its public
"id".
In essence, use GET to find out if a password is required, then send a POST
request to fetch the shareupload''s detail information and to verify the password,
if a password was set.'
parameters:
- description: ID of a specific shareupload
in: query
name: id
required: true
schema:
type: string
- description: Upload password, required if shareupload is protected by a password.
in: query
name: password
required: false
schema:
type: string
- description: 'Comma-separated list of response fields, that defines which
fields to appear in the response.
c&p friendly:
##download_code,has_password,id,name,remaining,size,status,ttl,type,uri
##
'
in: query
name: fields
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request (e.g. invalid parameter)
'403':
description: Forbidden
'404':
description: Not Found (e.g. shareupload does not exist)
'410':
description: Gone (e.g. shareupload expired)
'500':
description: Internal Error
security: []
summary: Fetch information about a shareupload referenced by its public "id"
tags:
- share
/shareupload/upload:
post:
description: Upload data for a given shareupload ID.
parameters:
- description: ID of a specific shareupload
in: query
name: id
required: true
schema:
type: string
- description: Provide a filename to store the uploaded file.
in: query
name: name
required: false
schema:
type: string
- description: The file to upload (required for multipart/form-data uploads)
in: query
name: file
required: true
schema:
$ref: '#/components/schemas/File'
- description: Upload password, required if set by the shareupload's creator.
in: query
name: password
required: false
schema:
type: string
responses:
'201':
description: Created (upload was successful)
'400':
description: Bad Request (e.g. invalid parameter)
'403':
description: Forbidden
'404':
description: Not Found (e.g. shareupload does not exist)
'410':
description: Gone (e.g. shareupload expired)
'415':
description: Unsupported Media Type
'500':
description: Internal Error
'507':
description: Insufficient Storage (e.g. not enough free space)
security: []
summary: Upload data for a given shareupload ID
tags:
- share
/snapshot:
delete:
description: 'Delete a given Snapshot. Super-user option: Set to the literal
"space" to enable access to otherwise not accessable snapshots.'
parameters:
- description: 'the zone of the snapshot
see Zone-API for more information'
in: query
name: zone
required: true
schema:
type: string
- description: the name of the snapshot
in: query
name: name
required: true
schema:
type: string
- description: 'Admin-Modifier, to extend or limit the entities considered for
the request.
**possible values:**
##"all" - use all existing entities (admin or owner privileges required)
"user" - only use entities related to authenticated user
##
'
in: query
name: scope
required: false
schema:
type: string
responses:
'204':
description: No Content
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (no authentication)
'403':
description: 'Forbidden (e.g. Forbidden: Insufficient privileges)'
'404':
description: Not Found (e.g. account not existing)
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Delete a given Snapshot
tags:
- snapshot
get:
description: Get a list of all snapshots for the authenticated user.
parameters:
- description: Path to show snapshots for (e.g. root/public/my/path)
in: query
name: path
required: false
schema:
type: string
- description: 'Admin-Modifier, to extend or limit the entities considered for
the request.
**possible values:**
##"all" - use all existing entities (admin or owner privileges required)
"user" - only use entities related to authenticated user
##
'
in: query
name: scope
required: false
schema:
type: string
responses:
'200':
content: {}
description: OK
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (no authentication)
'403':
description: Forbidden
'404':
description: Not Found
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Get a list of all snapshots for the authenticated user
tags:
- snapshot
post:
description: 'Create a new named snapshot.
Users can only create snapshots for their own home "zone", admins and owner
are allowed to create snapshots for all zones.
Attention: the creation of manual snapshots may be disabled by some versions
of HiDrive. See [L[/#cv#/features_GET]GET /#cv#/features] for details.'
parameters:
- description: 'the zone to create a new snapshot for
see Zone-API for more information'
in: query
name: zone
required: true
schema:
type: string
- description: a name for the snapshot, maximum length is 100 bytes
in: query
name: name
required: true
schema:
type: string
- description: 'Admin-Modifier, to extend or limit the entities considered for
the request.
**possible values:**
##"all" - use all existing entities (admin or owner privileges required)
"user" - only use entities related to authenticated user
##
'
in: query
name: scope
required: false
schema:
type: string
responses:
'201':
description: Created
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (no authentication)
'403':
description: 'Forbidden (e.g. Forbidden: Insufficient privileges)'
'409':
description: 'Conflict (e.g. conflict: snapshot <name> exists)'
'422':
description: Unprocessable Entity (e.g. snapshot name exceeds 100 bytes)
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Create a new named snapshot
tags:
- snapshot
put:
description: Rename a snapshot.
parameters:
- description: Snapshot zone name. See Zone-API for more information.
in: query
name: zone
required: true
schema:
type: string
- description: Snapshot name.
in: query
name: name
required: true
schema:
type: string
- description: New snapshot name. Maximum length is 100 bytes.
in: query
name: dst
required: true
schema:
type: string
- description: 'Admin-Modifier, to extend or limit the entities considered for
the request.
**possible values:**
##"all" - use all existing entities (admin or owner privileges required)
"user" - only use entities related to authenticated user
##
'
in: query
name: scope
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (no authentication)
'403':
description: 'Forbidden (e.g. Forbidden: Insufficient privileges)'
'404':
description: Not Found (e.g. snapshot <name> not existing)
'409':
description: 'Conflict (e.g. conflict: snapshot <name> exists)'
'422':
description: Unprocessable Entity (e.g. new snapshot name exceeds 100 bytes)
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- owner,rw
- owner,ro
- admin,rw
- admin,ro
summary: Rename a snapshot
tags:
- snapshot
/status/disabled:
get:
description: Returns the disabled-state of the HiDrive. The HiDrive access might
be restricted in case of unpayed invoice or abuse issues.
parameters: []
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'401':
description: Unauthorized
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Returns the disabled-state of the HiDrive
tags:
- status
/status/invite:
get:
description: Get the information about the state of inviting friends where in
some tariffs inviting friends, who will register a new HiDrive, will increase
the storage space or features of your own HiDrive
parameters: []
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'401':
description: Unauthorized
'500':
description: Internal Error
'503':
description: Service Unavailable
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Get the information about the state of inviting friends where in some
tariffs inviting friends, who will register a new HiDrive, will increase the
storage space or features of your own HiDrive
tags:
- status
/unique:
get:
description: 'Get a unique identifier that can be passed to the mailupload controller.
Along with the identifier this call returns a MAC (Message Authentication
Code) that proves that the identifier has been generated by this endpoint.
The MAC has to be passed to the receiving endpoint along with the identifier.'
parameters: []
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Get a unique identifier that can be passed to the mailupload controller
tags:
- unique
/user:
delete:
description: 'Delete a given user.
You cannot delete the user account that is used to call this method, i.e.
the currently authenticated user.
A user that has **is_owner** roles cannot be deleted at all!'
parameters:
- description: 'the ID of the account you want to delete
Example: 54321.3'
in: query
name: account
required: true
schema:
type: string
responses:
'204':
description: No Content
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (no authentication)
'403':
description: 'Forbidden (e.g. Forbidden: Insufficient privileges)'
'404':
description: Not Found (e.g. account not existing)
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- owner,rw
- owner,ro
- admin,rw
- admin,ro
summary: Delete a given user
tags:
- user
get:
description: 'Get data of account or specific account.
The optional fields parameter is a comma-separated list of field names, to
be included in the response. The default is account,alias.
! This resource requires owner or administrator role !'
parameters:
- description: 'accountID. Example: "54321.1"'
in: query
name: account
required: false
schema:
type: string
- description: 'Admin-Modifier, to extend or limit the entities considered for
the request.
**possible values:**
##"all" - use all existing entities (admin or owner privileges required)
"user" - only use entities related to authenticated user
##
'
in: query
name: scope
required: false
schema:
type: string
- description: 'Comma-separated list of response fields
Valid field names are:
##account - string - account id
alias - string - username
descr - string - description, e.g real name
email - string - current email address
email_pending - string - unverified new email address (after PUT /user)
email_verified - bool - has the current email address been verified
encrypted - bool - are secure protocols enforced
home - string - path to the home directory
home_id - string - pid of the home directory
is_admin - bool - does the user possess administrator privileges
is_owner - bool - does the user possess owner privileges
language - string - lowercase two-letter language tag
protocols - object - a list indicating which protocols are available
has_password - bool - has a password been set for the user
##
c&p friendly:
##account,alias,descr,email,email_pending,email_verified,encrypted,home,home_id,is_admin,is_owner,language,protocols,has_password
##
'
in: query
name: fields
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (no authentication)
'403':
description: 'Forbidden (Forbidden: Insufficient privileges)'
'404':
description: Not Found (e.g. account not existing)
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Get data of account or specific account
tags:
- user
post:
description: 'Create a new user.
the **protocols** parameter may also be set by submitting values as an array
(protocols=ftp&protocols=cifs&protocols=...)
if **is_admin** is set, keep in mind that there might be an admin-user limit.
The related error would be: { "msg" : "Forbidden: admin accounts limit
reached", "code" : "403" }'
parameters:
- description: 'a username (5 to 40 characters) that matches the regex:
^[a-z0-9][a-z0-9\-\.]{3,38}[a-z0-9]$'
in: query
name: alias
required: true
schema:
type: string
- description: 'a passphrase (6 to 20 characters) that matches the regex:
^[a-zA-Z0-9\!#\$%&\(\)\*\+,\-\.\/:;<>=\?@\[\]\^_\{\}\|~]{6,20}$'
in: query
name: password
required: true
schema:
type: string
- description: an e-mail adress
in: query
name: email
required: false
schema:
type: string
- description: descriptive text; a utf8 encoded string limited to 80 bytes without
LF (line feed, '\n', 0x0A) characters
in: query
name: descr
required: false
schema:
type: string
- description: grant admin privileges to the new user
in: query
name: is_admin
required: false
schema:
type: boolean
- description: Set true to enforce encrypted data connections only
in: query
name: encrypted
required: false
schema:
type: boolean
- description: A CSV list of protocols made available to the new user.
in: query
name: protocols
required: false
schema:
type: string
- description: Set with a lowercase two-letter language tag as per ISO 639-1:2000
(unvalidated). Pass an empty value to clear.
in: query
name: language
required: false
schema:
$ref: '#/components/schemas/LanguageCode'
- description: If set the user will receive mailings regarding the current status
of his HiDrive like storage allocation and share links on a regular basis.
in: query
name: statusmail
required: false
schema:
type: boolean
responses:
'201':
description: Created
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (no authentication)
'403':
description: 'Forbidden (e.g. Forbidden: Insufficient privileges)'
'409':
description: 'Conflict (e.g. conflict: alias name)'
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- owner,rw
- owner,ro
- admin,rw
- admin,ro
summary: Create a new user
tags:
- user
put:
description: 'Update user settings.
Users may only update their own data! Owners can only be edited by themselves.
Use only the params you want to update, other values stay as they are.
The **protocols** parameter may also be set by submitting values as an array
(protocols=ftp&protocols=cifs&protocols=...). Note that a change for this
parameter is not handled synchronously. A successful response indicates only
that the requested change will be made. Usually, the actual update takes just
a few seconds to be in effect.
Changing a user''s **alias** may fail if the user''s quota is exhausted.
If **is_admin** is set, keep in mind that there might be an admin-user limit.
The related error would be: { "msg" : "Forbidden: admin accounts limit
reached", "code" : "403" }
When the tariff requires email verification changing the email address results
in a confirmation email to the new address. The link in the mail is valid
for 24 hours. Until confirmation the old address remains the users **email**,
the new one is shown in **email_pending** and **email_verified** is false.
Once the address is confirmed, it is removed from **email_pending**, it becomes
the new **email**, and **email_verified** is true. If a third address is set
before confirmation, then the new one overwrites the currently pending email
address.'
parameters:
- description: 'the ID of the account you want to update
Example: 54321.3'
in: query
name: account
required: true
schema:
type: string
- description: 'a new username (5 to 40 characters) that matches the regex:
^[a-z0-9][a-z0-9\-\.]{3,38}[a-z0-9]$'
in: query
name: alias
required: false
schema:
type: string
- description: 'a new passphrase (6 to 20 characters) that matches the regex:
^[a-zA-Z0-9\!#\$%&\(\)\*\+,\-\.\/:;<>=\?@\[\]\^_\{\}\|~]{6,20}$'
in: query
name: password
required: false
schema:
type: string
- description: a new e-mail adress
in: query
name: email
required: false
schema:
type: string
- description: new descriptive text; a utf8 encoded string limited to 80 bytes
without LF (line feed, '\n', 0x0A) characters
in: query
name: descr
required: false
schema:
type: string
- description: grant admin privileges to the user
in: query
name: is_admin
required: false
schema:
type: boolean
- description: Set true to enforce encrypted data connections only
in: query
name: encrypted
required: false
schema:
type: boolean
- description: A CSV list of protocols made available to the user. Changes for
this parameter are not synchronous but usually happen within seconds.
in: query
name: protocols
required: false
schema:
type: string
- description: Set with a lowercase two-letter language tag as per ISO 639-1:2000
(unvalidated). Pass an empty value to clear.
in: query
name: language
required: false
schema:
$ref: '#/components/schemas/LanguageCode'
- description: If set the user will receive mailings regarding the current status
of his HiDrive like storage allocation and share links on a regular basis.
in: query
name: statusmail
required: false
schema:
type: boolean
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (no authentication)
'403':
description: 'Forbidden (e.g. Forbidden: Insufficient privileges)'
'404':
description: Not Found (e.g. account not existing)
'409':
description: 'Conflict (e.g. conflict: alias name)'
'500':
description: Internal Error
'507':
description: Insufficient Storage
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Update user settings
tags:
- user
/user/2fa:
delete:
description: Remove the secret for the Google TOTP generation of the currently
authenticated account.
parameters: []
responses:
'204':
description: No Content
'401':
description: Unauthorized (no authentication)
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Remove the secret for the Google TOTP generation of the currently authenticated
account
tags:
- user
post:
description: Add a secret for the Google TOTP generation of the currently authenticated
account.
parameters:
- description: secret used to generate the TOTP. Example "666"
in: query
name: secret
required: true
schema:
type: string
- description: token to verify the given secret
in: query
name: verify_token
required: true
schema:
type: string
responses:
'204':
description: No Content
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (no authentication)
'403':
description: 'Forbidden (e.g. Forbidden: Insufficient privileges)'
'409':
description: Conflict (e.g. secret/token do not match)
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Add a secret for the Google TOTP generation of the currently authenticated
account
tags:
- user
/user/2fa/reset:
post:
description: 'This call is the first step to recover from a forgotten 2FA secret.
An email will be sent to the user''s email address. It contains a temporary
authentication token and instructions on how to set a new secret. The second
step is to login with this token (that can only be used once) and to set a
new secret for the account.
This endpoint requires username and password to trigger the reset e-mail.
It is impossible to use this endpoint with a password-reset-token.'
parameters:
- description: username of the account that lost the 2FA secret.
in: query
name: alias
required: true
schema:
type: string
- description: the passphrase of the account.
in: query
name: password
required: true
schema:
type: string
- description: A two-letter code for the language you want the email to be sent
in.
in: query
name: lang
required: false
schema:
type: string
responses:
'204':
description: No Content (email was sent successfully)
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (e.g. invalid credentials)
'403':
description: Forbidden (e.g. user space is locked)
'422':
description: Unprocessable Entity (e.g. no email address on file)
'424':
description: Failed Dependency (there is no secret, i.e. user does not use
2FA)
'500':
description: Internal Error
'503':
description: Service Unavailable
security: []
summary: This call is the first step to recover from a forgotten 2FA secret
tags:
- user
/user/available:
get:
description: 'Creating a new user requires an **alias** parameter, use this
call to check if a chosen alias is available and/or to suggests up to five
alternative aliases.
If the **alias** parameter it set, **available** will indicate if the requested
alias is still available for creation of a new user.
When **suggestions** is set to false and no **alias** parameter is provided,
the response will be empty (204 No Content).
**NOTE:** This endpoint accepts legacy alias formats for historical reasons.
It is possible that GET /user/available returns HTTP 200 (OK) and even ##available:
true## for a given alias, but subsequent calls to POST /user or PUT /user
fail with HTTP 400, because the alias in question does not comply with the
current formalities for account aliases.'
parameters:
- description: a requested alias
in: query
name: alias
required: false
schema:
type: string
- description: get 5 suggestions. For aliases that look like email addresses
this parameter will be ignored and no suggestions will be included in the
response.
in: query
name: suggestions
required: false
schema:
type: boolean
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'204':
description: No Content
'400':
description: Bad Request (e.g. invalid alias format)
'500':
description: Internal Error
security: []
summary: Creating a new user requires an **alias** parameter, use this call
to check if a chosen alias is available and/or to suggests up to five alternative
aliases
tags:
- user
/user/finger:
get:
description: Check for an alias name. A return code of 404 indicates, that the
alias is not used, which is probably the information, the caller wants the
see. An empty response with a return code of 204 means, that the requested
alias name is already taken.
parameters:
- description: An alias name
in: query
name: alias
required: true
schema:
type: string
responses:
'204':
description: No Content (alias exists)
'400':
description: Bad Request (e.g. invalid parameter)
'404':
description: Not Found (e.g. alias not taken)
'500':
description: Internal Error
security: []
summary: Check for an alias name
tags:
- user
/user/invite:
delete:
description: Delete a pending invitation.
parameters:
- description: the id returned from from POST /user/invite
in: query
name: invite_id
required: true
schema:
type: string
responses:
'204':
description: No Content
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (no authentication)
'403':
description: 'Forbidden (e.g. Forbidden: Insufficient privileges)'
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- owner,rw
- owner,ro
- admin,rw
- admin,ro
summary: Delete a pending invitation
tags:
- user
get:
description: 'If no invite_id is given, show all pending intivitations. If an
invite_id is given, report details only for this one.
See POST /user/invite for details.'
parameters:
- description: 'Comma-separated list of response fields. Valid fields are: email,descr,is_admin,encrypted,statusmail,protocols,
language,invite_id,invite_date,permissions,permissions.pid, permissions.path,permissions.readable,permissions.writable
If fields is not given, all fields are returned.'
in: query
name: fields
required: false
schema:
type: string
- description: if given, only information for this invite_id will be returned
in: query
name: invite_id
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'401':
description: Unauthorized (no authentication)
'403':
description: 'Forbidden (e.g. Forbidden: Insufficient privileges)'
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- owner,rw
- owner,ro
- admin,rw
- admin,ro
summary: If no invite_id is given, show all pending intivitations
tags:
- user
post:
description: 'Invite a user into the package. This endpoint triggers an invitation
e-mail to be sent. If the recipient accepts the invitation, an account with
the given parameters will be created and the initiator will be notified if
she has a valid e-mail address configured.
The **protocols** parameter may also be set by submitting values as an array
(protocols=ftp&protocols=cifs&protocols=...)
Note that the invite_id can also be used as a parameter to PUT /permission
to set additional access rights to the invitation.'
parameters:
- description: the e-mail adress of the user to invite. It will be used to send
an invitation email. Depending on the tariff it might be required that the
address does not yet exist in the system
in: query
name: email
required: true
schema:
type: string
- description: the full name of the user; a utf8 encoded string limited to 80
bytes without LF (line feed, '\n', 0x0A) characters.
in: query
name: descr
required: true
schema:
type: string
- description: grant admin privileges to the new user
in: query
name: is_admin
required: false
schema:
type: boolean
- description: Set true to enforce encrypted data connections only
in: query
name: encrypted
required: false
schema:
type: boolean
- description: A CSV list of protocols made available to the new user.
in: query
name: protocols
required: false
schema:
type: string
- description: Set with a lowercase two-letter language tag as per ISO 639-1:2000
(unvalidated).
in: query
name: language
required: false
schema:
$ref: '#/components/schemas/LanguageCode'
- description: If set the user will receive mailings regarding the current status
of his HiDrive like storage allocation and share links on a regular basis.
in: query
name: statusmail
required: false
schema:
type: boolean
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'204':
description: No Content
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (no authentication)
'403':
description: 'Forbidden (e.g. Forbidden: Insufficient privileges)'
'409':
description: 'Conflict (e.g. conflict: alias name)'
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- owner,rw
- owner,ro
- admin,rw
- admin,ro
summary: Invite a user into the package
tags:
- user
/user/invite/confirm:
post:
description: Completion of the invitation process. After the user has provided
the missing information, they have to be presented to this endpoint, along
with the token generated from POST /user/invite. The call will in turn create
the user and return information about it.
parameters:
- description: the token contained in the invitation email
in: query
name: invite_token
required: true
schema:
type: string
- description: 'a username (5 to 40 characters) that matches the regex:
^[a-z0-9][a-z0-9\-\.]{3,38}[a-z0-9]$'
in: query
name: alias
required: true
schema:
type: string
- description: 'a passphrase (6 to 20 characters) that matches the regex:
^[a-zA-Z0-9\!#\$%&\(\)\*\+,\-\.\/:;<>=\?@\[\]\^_\{\}\|~]{6,20}$'
in: query
name: password
required: true
schema:
type: string
responses:
'201':
description: Created
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (invalid token)
'409':
description: 'Conflict (e.g. conflict: alias name)'
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2: []
summary: Completion of the invitation process
tags:
- user
/user/invite/info:
get:
description: Report details for the given invite_token.
parameters:
- description: The invite token for which to query information
in: query
name: invite_token
required: true
schema:
type: string
- description: Comma-separated list of response fields
in: query
name: fields
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'401':
description: Unauthorized (no authentication)
'403':
description: 'Forbidden (e.g. Forbidden: Insufficient privileges)'
'409':
description: Conflict (the given invite_token has already been confirmed)
'410':
description: Gone (the given invite_token has expired)
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2: []
summary: Report details for the given invite_token
tags:
- user
/user/key:
delete:
description: 'Delete a public key from the authorized_keys file. On success,
a 204 response code is returned.
Without the optional **account** parameter, the referenced key will be deleted
from authorized_keys file of the currently authenticated account.
When an account is specified by passing the **account** parameter, the key
will be deleted from the authorized_keys file of that account.
When an account is specified by passing the **account** parameter, the public
key will be deleted from the authorized_keys file of that account. Accessing
an account that is not the currently authenticated account requires administrator
or owner roles.'
parameters:
- description: 'accountID. Example: "54321.1"'
in: query
name: account
required: false
schema:
type: string
- description: 'key ID. Example: "1325372400.12345.4"'
in: query
name: id
required: true
schema:
type: string
responses:
'204':
description: No Content (key deleted)
'400':
description: Bad Request (invalid key and/or account)
'401':
description: Unauthorized (no authentication)
'403':
description: 'Forbidden (e.g. Forbidden: Insufficient privileges)'
'404':
description: Not Found (referenced account or keyid does not exist)
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Delete a public key from the authorized_keys file
tags:
- user
get:
description: 'List meta-data about the authorized public keys for an account.
The optional **account** parameter determines the account and defaults to
the currently authenticated account. Accessing data of an account that is
not the currently authenticated account requires administrator or owner roles.
For an account without authorized keys, the authkey data struct array is empty.
To fetch data for a single public key, pass the keyID in the optional **id**
parameter.'
parameters:
- description: 'accountID. Example: "54321.1"'
in: query
name: account
required: false
schema:
type: string
- description: 'keyID. Example: "1325372400.12345.4"'
in: query
name: id
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'401':
description: Unauthorized (no authentication)
'403':
description: 'Forbidden (e.g. Forbidden: Insufficient privileges)'
'404':
description: Not Found (referenced account/key does not exist)
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: List meta-data about the authorized public keys for an account
tags:
- user
post:
description: 'Add a single public key to the authorized_keys file for an account.
The **keydata** parameter can contain either a single line (as copied from
an existing authorized_keys file) or the contents of a public key file in
the SECSH format (http://tools.ietf.org/html/rfc4716) for RSA, DSA and ED25519
Keys. ECDSA Keys must be in the SSH ECC format (https://tools.ietf.org/html/rfc5656).
RSA, DSA, ECDSA and ED25519 ssh2 keys are accepted. Invalid, malformatted
and ssh1 keys will be rejected with status code 400 and an error message containing
details about the error.
The optional **comment** parameter can be used to add a short description,
otherwise the comment from the key data itself will be used.
Without the optional **account** parameter, the public key will be added to
the authorized_keys file of the currently authenticated account.
When an account is specified by passing the **account** parameter, the public
key will be added to the authorized_keys file of that account. Accessing an
account that is not the currently authenticated account requires administrator
or owner roles.'
parameters:
- description: 'accountID. Example: "54321.1"'
in: query
name: account
required: true
schema:
type: string
- description: public key data
in: query
name: keydata
required: false
schema:
type: string
- description: comment for the public key
in: query
name: comment
required: false
schema:
type: string
responses:
'201':
description: Created
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (no authentication)
'403':
description: 'Forbidden (e.g. Forbidden: Insufficient privileges)'
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Add a single public key to the authorized_keys file for an account
tags:
- user
/user/me_new:
get:
description: Get data of authenticated User.
parameters:
- description: 'Comma-separated list of response fields
Valid field names are:
##account - string - account id
alias - string - username
descr - string - description, e.g real name
email - string - current email address
email_pending - string - unverified new email address (after PUT /user)
email_verified - bool - has the current email address been verified
encrypted - bool - are secure protocols enforced
home - string - path to the home directory
home_id - string - pid of the home directory
is_admin - bool - does the user possess administrator privileges
is_owner - bool - does the user possess owner privileges
language - string - lowercase two-letter language tag
protocols - object - a list indicating which protocols are available
has_password - bool - has a password been set for the user
##
c&p friendly:
##account,alias,descr,email,email_pending,email_verified,encrypted,home,home_id,is_admin,is_owner,language,protocols,has_password
##
The default is ##account,alias##.'
in: query
name: fields
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (no authentication)
'403':
description: 'Forbidden (Forbidden: Insufficient privileges)'
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: Get data of authenticated User
tags:
- user
/user/password:
put:
description: This is step two of the process to recover from a forgotten password.
Once [L[/#cv#/user/password/reset_POST]POST /#cv#/user/password/reset] has
been called, the user receives an email with instructions and an URL to click
on that has an embedded authentication token code. This call expects the new
password to be set along with this token to autheticate the request. After
the new password has been set sucessfully, the token becomes unusable.
parameters:
- description: username of the user to reset password for.
in: query
name: alias
required: true
schema:
type: string
- description: 'new passphrase (6 to 20 characters) that matches the regex:
^[a-zA-Z0-9\!#\$%&\(\)\*\+,\-\.\/:;<>=\?@\[\]\^_\{\}\|~]{6,20}$'
in: query
name: password
required: true
schema:
type: string
- description: reset token as specified in the pw-reset email (embedded in link).
in: query
name: token
required: true
schema:
type: string
- description: the 2fa token is required to set a new password when two-factor
authentication has been activated. Otherwise this parameter is ignored.
in: query
name: otptoken
required: false
schema:
type: string
responses:
'204':
description: No Content (password successfully reset)
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (no authenticated token)
'403':
description: Forbidden (e.g. user space is locked)
'404':
description: Not Found (user does not exist)
'422':
description: 'Unprocessable Entity (2fa enabled: otptoken required)'
'500':
description: Internal Error
security: []
summary: This is step two of the process to recover from a forgotten password
tags:
- user
/user/password/reset:
post:
description: 'This call is the first step to recover from a forgotten user password.
An email will be sent to the user''s email address filed during sign-up. It
contains instructions on how to set a new password and a link with an embedded
authentication token that can only be used once to set a new password for
this account.
See [L[/#cv#/user/password_PUT]PUT /#cv#/user/password] for the next step.'
parameters:
- description: username of the account to reset the password for.
in: query
name: alias
required: true
schema:
type: string
- description: 'Alternative url for setting a new password
The URL defaults to https://hidrive.strato.com/?fpw=<token>, but can be
replaced by an individual target using the **url** parameter. It is matched
against a whitelist. Other values will result in 400 Bad Request.'
in: query
name: url
required: false
schema:
type: string
- description: A two-letter code for the language you want the password reset
email to be sent in.
in: query
name: lang
required: false
schema:
type: string
responses:
'204':
description: No Content (password reset email was sent successfully)
'400':
description: Bad Request (e.g. invalid parameter)
'403':
description: Forbidden (e.g. user space is locked)
'404':
description: Not Found (user does not exist)
'422':
description: Unprocessable Entity (e.g. no email address on file)
'500':
description: Internal Error
'503':
description: Service Unavailable
security: []
summary: This call is the first step to recover from a forgotten user password
tags:
- user
/zone:
get:
description: 'The /zone resource returns a named list of folders and their zone
settings. The list will contain all settings in the caller''s package, as
long as the caller has read access in that folder.
Setting apply to the folder, and all folders inside it, unless a new zone
setting is active further down.'
parameters:
- description: 'Admin-Modifier, to extend or limit the entities considered for
the request.
**possible values:**
##"all" - use all existing entities (admin or owner privileges required)
"user" - only use entities related to authenticated user
##
'
in: query
name: scope
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (no authentication)
'403':
description: 'Forbidden (Forbidden: Insufficient privileges)'
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- admin,rw
- admin,ro
- owner,rw
- user,ro
- user,rw
- owner,ro
summary: The /zone resource returns a named list of folders and their zone settings
tags:
- zone
put:
description: Update quota or snapshot schedule of a zone.
parameters:
- description: 'Local path name of the zone
Example root/users/foobar'
in: query
name: name
required: true
schema:
type: string
- description: 'The file system quota in bytes to be set for a specified zone
(name). A positive integer in order to set, or empty to withdraw a quota.
**hint:** Setting a quota requires Owner or Admin roles and is not allowed
for the "root" zone, since that quota is defined by the available space
of the purchased HiDrive package.'
in: query
name: quota
required: false
schema:
type: number
- description: 'A snapshot schedule, "schedule:holdback_time".
**sched** value might look like: "1d:6m" meaning, create daily automated
snapshots, storing them for 6 months (for more information consult the related
documentation on snapshots). The minimum schedule interval value is "4h".
Updating the snapshot schedule is related to package-feature based limitations
(as to the maximum holdback_time).
Set to "none" in order to remove any snapshot schedule, i.e. no automated
backups will be created for that zone.
Set to "inherit" if you want this zone to have the same snapshot schedule
as its parent. For example root/users/foobar could inherit the schedule
from root/users. The "root" zone cannot inherit its schedule.
**hint:** Without Owner or Admin roles, a schedule can only be set for the
authenticated users zone (e.g. root/users/USERNAME)'
in: query
name: sched
required: false
schema:
type: string
- description: 'Admin-Modifier, to extend or limit the entities considered for
the request.
**possible values:**
##"all" - use all existing entities (admin or owner privileges required)
"user" - only use entities related to authenticated user
##
It is only possible to set both quota and schedule for zones without write
roles (e.g. other users'' zones) if scope=all is set.'
in: query
name: scope
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
type: object
description: OK
'400':
description: Bad Request (e.g. invalid parameter)
'401':
description: Unauthorized (no authentication)
'403':
description: 'Forbidden (Forbidden: Insufficient privileges)'
'404':
description: Not Found (e.g. zone not existing)
'500':
description: Internal Error
security:
- BearerAuth: []
- oAuth2:
- owner,rw
- owner,ro
- admin,rw
- admin,ro
summary: Update quota or snapshot schedule of a zone
tags:
- zone
components:
schemas:
User:
type: object
required:
- account
- alias
properties:
account:
type: string
description: "username"
alias:
type: string
description: "username"
descr:
type: string
description: "description, e.g real name"
email:
type: string
description: "current email address"
email_pending:
type: string
description: "unverified new email address (after PUT /user)"
email_verified:
type: boolean
description: "has the current email address been verified"
encrypted:
type: boolean
description: "are secure protocols enforced"
home:
type: string
description: "path to the home directory"
home_id:
type: string
description: "pid of the home directory"
is_admin:
type: boolean
description: "does the user possess administrator privileges"
is_owner:
type: boolean
description: "does the user possess owner privileges"
language:
type: string
description: "lowercase two-letter language tag"
protocols:
$ref: '#/components/schemas/Protocols'
has_password:
type: boolean
description: "has a password been set for the user"
Protocols:
type: object
description: "a list indicating which protocols are available"
properties:
git:
type: boolean
ftp:
type: boolean
rsync:
type: boolean
webdav:
type: boolean
scp:
type: boolean
cifs:
type: boolean
Timestamp:
type: number
description: "unix timestamp"
File:
type: string
description: "file contents"
Directory:
type: object
description: "directory model"
required:
- path
properties:
ctime:
$ref: '#/components/schemas/Timestamp'
has_dirs:
type: boolean
description: does the directory contain subdirs?
id:
type: string
description: path id of the directory
mtime:
$ref: '#/components/schemas/Timestamp'
name:
type: string
description: URL-encoded name of the directory
path:
type: string
description: URL-encoded path to the directory
readable:
type: boolean
description: read-permission for the directory
type:
type: string
description: "dir"
writable:
type: boolean
description: write-permission for the directory
LanguageCode:
type: string
description: "ISO 639-1 language name. lowercase"
maxLength: 2
minLength: 2
# Reusable path, query, header and cookie parameters
parameters: {}
securitySchemes:
BearerAuth:
type: http
scheme: bearer
oAuth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: 'https://my.hidrive.com/client/authorize'
tokenUrl: 'https://my.hidrive.com/oauth2/token'
scopes:
user,ro: Grants access to user read only operations
user,rw: Grants access to user write operations
admin,ro: Grants access to admin read only operations
admin,rw: Grants access to admin write operations
owner,rw: Grants access to owner read only operations
owner,ro: Grants access to owner operations
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment