123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560 |
- namespace files
- "This namespace contains endpoints and data types for basic file operations."
- import async
- import auth
- import common
- import users_common
- import properties
- alias Id = String(min_length=1)
- alias Path = String(pattern="/(.|[\\r\\n])*")
- alias PathOrId = String(pattern="/(.|[\\r\\n])*|id:.*|(ns:[0-9]+(/.*)?)")
- alias PathR = String(pattern="(/(.|[\\r\\n])*)?|(ns:[0-9]+(/.*)?)") # A path that can be the root path ("").
- alias Rev = String(min_length=9, pattern="[0-9a-f]+") # TODO: Change pattern to "rev:[0-9a-f]{9,}"
- alias ListFolderCursor = String(min_length=1)
- alias ReadPath = String(pattern="(/(.|[\\r\\n])*|id:.*)|(rev:[0-9a-f]{9,})|(ns:[0-9]+(/.*)?)")
- alias WritePath = String(pattern="(/(.|[\\r\\n])*)|(ns:[0-9]+(/.*)?)")
- alias Sha256HexHash = String(min_length=64, max_length=64)
- #
- # Metadata definitions and route
- #
- struct Metadata
- "Metadata for a file or folder."
- union_closed
- file FileMetadata
- folder FolderMetadata
- deleted DeletedMetadata # Used by list_folder* and search
- name String
- "The last component of the path (including extension).
- This never contains a slash."
- path_lower String?
- "The lowercased full path in the user's Dropbox. This always starts with a slash.
- This field will be null if the file or folder is not mounted."
- path_display String?
- "The cased path to be used for display purposes only. In rare instances the casing will not
- correctly match the user's filesystem, but this behavior will match the path provided in
- the Core API v1, and at least the last path component will have the correct casing. Changes
- to only the casing of paths won't be returned by :route:`list_folder/continue`. This field
- will be null if the file or folder is not mounted."
- parent_shared_folder_id common.SharedFolderId?
- "Deprecated. Please use :field:`FileSharingInfo.parent_shared_folder_id`
- or :field:`FolderSharingInfo.parent_shared_folder_id` instead."
- example default
- file = default
- example folder_metadata
- folder = default
- struct SharingInfo
- "Sharing info for a file or folder."
- read_only Boolean
- "True if the file or folder is inside a read-only shared folder."
- example default
- read_only = false
- struct FileSharingInfo extends SharingInfo
- "Sharing info for a file which is contained by a shared folder."
- parent_shared_folder_id common.SharedFolderId
- "ID of shared folder that holds this file."
- modified_by users_common.AccountId?
- "The last user who modified the file. This field will be null if
- the user's account has been deleted."
- example default
- read_only = true
- parent_shared_folder_id = "84528192421"
- modified_by = "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"
- struct FolderSharingInfo extends SharingInfo
- "Sharing info for a folder which is contained in a shared folder or is a
- shared folder mount point."
- parent_shared_folder_id common.SharedFolderId?
- "Set if the folder is contained by a shared folder."
- shared_folder_id common.SharedFolderId?
- "If this folder is a shared folder mount point, the ID of the shared
- folder mounted at this location."
- traverse_only Boolean = false
- "Specifies that the folder can only be traversed and the user can only see
- a limited subset of the contents of this folder because they don't have
- read access to this folder. They do, however, have access to some sub folder."
- no_access Boolean = false
- "Specifies that the folder cannot be accessed by the user."
- example default
- "Folder inside a shared folder."
- read_only = false
- parent_shared_folder_id = "84528192421"
- example shared_folder
- "Read-only shared folder mount point."
- read_only = true
- shared_folder_id = "84528192421"
- struct Dimensions
- "Dimensions for a photo or video."
- height UInt64
- "Height of the photo/video."
- width UInt64
- "Width of the photo/video."
- example default
- height = 768
- width = 1024
- struct GpsCoordinates
- "GPS coordinates for a photo or video."
- latitude Float64
- "Latitude of the GPS coordinates."
- longitude Float64
- "Longitude of the GPS coordinates."
- example default
- latitude = 37.7833
- longitude = 122.4167
- struct MediaMetadata
- "Metadata for a photo or video."
- union_closed
- photo PhotoMetadata
- video VideoMetadata
- dimensions Dimensions?
- "Dimension of the photo/video."
- location GpsCoordinates?
- "The GPS coordinate of the photo/video."
- time_taken common.DropboxTimestamp?
- "The timestamp when the photo/video is taken."
- struct PhotoMetadata extends MediaMetadata
- "Metadata for a photo."
- example default
- dimensions = default
- location = default
- time_taken = "2015-05-12T15:50:38Z"
- struct VideoMetadata extends MediaMetadata
- "Metadata for a video."
- duration UInt64?
- "The duration of the video in milliseconds."
- example default
- dimensions = default
- location = default
- time_taken = "2015-05-12T15:50:38Z"
- duration = 1000
- union_closed MediaInfo
- pending
- "Indicate the photo/video is still under processing and metadata is
- not available yet."
- metadata MediaMetadata
- "The metadata for the photo/video."
- struct FileMetadata extends Metadata
- id Id
- "A unique identifier for the file."
- client_modified common.DropboxTimestamp
- "For files, this is the modification time set by the desktop client
- when the file was added to Dropbox. Since this time is not verified
- (the Dropbox server stores whatever the desktop client sends up), this
- should only be used for display purposes (such as sorting) and not,
- for example, to determine if a file has changed or not."
- server_modified common.DropboxTimestamp
- "The last time the file was modified on Dropbox."
- rev Rev
- "A unique identifier for the current revision of a file. This field is
- the same rev as elsewhere in the API and can be used to detect changes
- and avoid conflicts."
- size UInt64
- "The file size in bytes."
- media_info MediaInfo?
- "Additional information if the file is a photo or video."
- sharing_info FileSharingInfo?
- "Set if this file is contained in a shared folder."
- property_groups List(properties.PropertyGroup)?
- "Additional information if the file has custom properties with the
- property template specified."
- has_explicit_shared_members Boolean?
- "This flag will only be present if include_has_explicit_shared_members
- is true in :route:`list_folder` or :route:`get_metadata`. If this
- flag is present, it will be true if this file has any explicit shared
- members. This is different from sharing_info in that this could be true
- in the case where a file has explicit members but is not contained within
- a shared folder."
- content_hash Sha256HexHash?
- "A hash of the file content. This field can be used to verify data integrity. For more
- information see our :link:`Content hash /developers/reference/content-hash` page."
- example default
- id = "id:a4ayc_80_OEAAAAAAAAAXw"
- name = "Prime_Numbers.txt"
- path_lower = "/homework/math/prime_numbers.txt"
- path_display = "/Homework/math/Prime_Numbers.txt"
- sharing_info = default
- client_modified = "2015-05-12T15:50:38Z"
- server_modified = "2015-05-12T15:50:38Z"
- rev = "a1c10ce0dd78"
- size = 7212
- property_groups = [default]
- has_explicit_shared_members = false
- content_hash = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
- struct FolderMetadata extends Metadata
- id Id
- "A unique identifier for the folder."
- shared_folder_id common.SharedFolderId?
- "Deprecated. Please use :field:`sharing_info` instead."
- sharing_info FolderSharingInfo?
- "Set if the folder is contained in a shared folder or is a shared folder mount point."
- property_groups List(properties.PropertyGroup)?
- "Additional information if the file has custom properties with the
- property template specified."
- example default
- id = "id:a4ayc_80_OEAAAAAAAAAXz"
- path_lower = "/homework/math"
- path_display = "/Homework/math"
- name = "math"
- sharing_info = default
- property_groups = [default]
- struct DeletedMetadata extends Metadata
- "Indicates that there used to be a file or folder at this path, but it no longer exists."
- # TODO: Do we care about whether it's a deleted file or folder?
- # TODO: Add the mtime when it's been deleted? And the rev???
- example default
- path_lower = "/homework/math/pi.txt"
- path_display = "/Homework/math/pi.txt"
- name = "pi.txt"
- union_closed GetMetadataError
- path LookupError
- struct GetMetadataArg
- path ReadPath
- "The path of a file or folder on Dropbox."
- include_media_info Boolean = false
- "If true, :field:`FileMetadata.media_info` is set for photo and video."
- include_deleted Boolean = false
- "If true, :type:`DeletedMetadata` will be returned for deleted file or
- folder, otherwise :field:`LookupError.not_found` will be returned."
- include_has_explicit_shared_members Boolean = false
- "If true, the results will include a flag for each file indicating whether or not
- that file has any explicit members."
- example default
- path = "/Homework/math"
- example id
- path = "id:a4ayc_80_OEAAAAAAAAAYa"
- example rev
- path = "rev:a1c10ce0dd78"
- route get_metadata (GetMetadataArg, Metadata, GetMetadataError)
- "Returns the metadata for a file or folder.
- Note: Metadata for the root folder is unsupported."
- attrs
- owner = "dev-plat"
- allow_app_folder_app = true
- takes_path_root = true
- #
- # List folder routes
- #
- struct ListFolderLongpollArg
- cursor ListFolderCursor
- "A cursor as returned by :route:`list_folder` or :route:`list_folder/continue`. Cursors
- retrieved by setting :field:`ListFolderArg.include_media_info` to :val:`true` are not
- supported."
- timeout UInt64(min_value=30, max_value=480) = 30
- "A timeout in seconds. The request will block for at most this length
- of time, plus up to 90 seconds of random jitter added to avoid the
- thundering herd problem. Care should be taken when using this
- parameter, as some network infrastructure does not support long
- timeouts."
- example default
- cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
- struct ListFolderLongpollResult
- changes Boolean
- "Indicates whether new changes are available. If true, call
- :route:`list_folder/continue` to retrieve the changes."
- backoff UInt64?
- "If present, backoff for at least this many seconds before calling
- :route:`list_folder/longpoll` again."
- example default
- changes = true
- union ListFolderLongpollError
- reset
- "Indicates that the cursor has been invalidated. Call
- :route:`list_folder` to obtain a new cursor."
- route list_folder/longpoll (ListFolderLongpollArg, ListFolderLongpollResult, ListFolderLongpollError)
- "A longpoll endpoint to wait for changes on an account. In conjunction with
- :route:`list_folder/continue`, this call gives you a low-latency way to
- monitor an account for file changes. The connection will block until there
- are changes available or a timeout occurs. This endpoint is useful mostly
- for client-side apps. If you're looking for server-side notifications,
- check out our
- :link:`webhooks documentation https://www.dropbox.com/developers/reference/webhooks`."
- attrs
- host = "notify"
- auth = "noauth"
- owner = "dev-plat"
- allow_app_folder_app = true
- struct ListFolderArg
- path PathR
- "The path to the folder you want to see the contents of."
- recursive Boolean = false
- "If true, the list folder operation will be applied recursively to all subfolders
- and the response will contain contents of all subfolders."
- include_media_info Boolean = false
- "If true, :field:`FileMetadata.media_info` is set for photo and video."
- include_deleted Boolean = false
- "If true, the results will include entries for files and folders that used to exist but were deleted."
- include_has_explicit_shared_members Boolean = false
- "If true, the results will include a flag for each file indicating whether or not
- that file has any explicit members."
- example default
- path = "/Homework/math"
- recursive = false
- struct ListFolderResult
- entries List(Metadata)
- "The files and (direct) subfolders in the folder."
- cursor ListFolderCursor
- "Pass the cursor into :route:`list_folder/continue` to see what's
- changed in the folder since your previous query."
- has_more Boolean
- "If true, then there are more entries available. Pass the
- cursor to :route:`list_folder/continue` to retrieve the rest."
- example default
- entries = [default, folder_metadata]
- cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
- has_more = false
- union ListFolderError
- path LookupError
- route list_folder (ListFolderArg, ListFolderResult, ListFolderError)
- "Starts returning the contents of a folder. If the result's :field:`ListFolderResult.has_more`
- field is :val:`true`, call :route:`list_folder/continue` with the returned
- :field:`ListFolderResult.cursor` to retrieve more entries.
- If you're using :field:`ListFolderArg.recursive` set to :val:`true` to keep a local cache of
- the contents of a Dropbox account, iterate through each entry in order and process them as
- follows to keep your local state in sync:
- For each :type:`FileMetadata`, store the new entry at the given path in your local state. If the
- required parent folders don't exist yet, create them. If there's already something else at the
- given path, replace it and remove all its children.
- For each :type:`FolderMetadata`, store the new entry at the given path in your local state. If
- the required parent folders don't exist yet, create them. If there's already something else at
- the given path, replace it but leave the children as they are. Check the new entry's
- :field:`FolderSharingInfo.read_only` and set all its children's read-only statuses to match.
- For each :type:`DeletedMetadata`, if your local state has something at the given path, remove it
- and all its children. If there's nothing at the given path, ignore this entry.
- Note: :type:`auth.RateLimitError` may be returned if multiple :route:`list_folder` or
- :route:`list_folder/continue` calls with same parameters are made simultaneously by same
- API app for same user. If your app implements retry logic, please hold off the retry until
- the previous request finishes."
- attrs
- owner = "dev-plat"
- allow_app_folder_app = true
- struct ListFolderContinueArg
- cursor ListFolderCursor
- "The cursor returned by your last call to :route:`list_folder` or
- :route:`list_folder/continue`."
- example default
- cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
- union ListFolderContinueError
- path LookupError
- reset
- "Indicates that the cursor has been invalidated. Call
- :route:`list_folder` to obtain a new cursor."
- route list_folder/continue (ListFolderContinueArg, ListFolderResult, ListFolderContinueError)
- "Once a cursor has been retrieved from :route:`list_folder`, use this to paginate through all
- files and retrieve updates to the folder, following the same rules as documented for
- :route:`list_folder`."
- attrs
- owner = "dev-plat"
- allow_app_folder_app = true
- struct ListFolderGetLatestCursorResult
- cursor ListFolderCursor
- "Pass the cursor into :route:`list_folder/continue` to see what's
- changed in the folder since your previous query."
- example default
- cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
- route list_folder/get_latest_cursor (ListFolderArg, ListFolderGetLatestCursorResult, ListFolderError)
- "A way to quickly get a cursor for the folder's state. Unlike :route:`list_folder`,
- :route:`list_folder/get_latest_cursor` doesn't return any entries. This endpoint is for app
- which only needs to know about new files and modifications and doesn't need to know about
- files that already exist in Dropbox."
- attrs
- owner = "dev-plat"
- allow_app_folder_app = true
- #
- # Download
- #
- union DownloadError
- path LookupError
- struct DownloadArg
- path ReadPath
- "The path of the file to download."
- rev Rev?
- "Deprecated. Please specify revision in :field:`path` instead."
- example default
- path = "/Homework/math/Prime_Numbers.txt"
- example id
- path = "id:a4ayc_80_OEAAAAAAAAAYa"
- example rev
- path = "rev:a1c10ce0dd78"
- route download (DownloadArg, FileMetadata, DownloadError)
- "Download a file from a user's Dropbox."
- attrs
- host = "content"
- style = "download"
- owner = "dev-plat"
- allow_app_folder_app = true
- #
- # Upload Routes
- #
- # Errors
- struct UploadWriteFailed
- reason WriteError
- "The reason why the file couldn't be saved."
- upload_session_id String
- "The upload session ID; this may be used to retry the commit."
- union UploadError
- path UploadWriteFailed
- "Unable to save the uploaded contents to a file."
- struct UploadSessionOffsetError
- correct_offset UInt64
- "The offset up to which data has been collected."
- union UploadSessionLookupError
- not_found
- "The upload session ID was not found or has expired. Upload sessions are
- valid for 48 hours."
- incorrect_offset UploadSessionOffsetError
- "The specified offset was incorrect. See the value for the
- correct offset. This error may occur when a previous request
- was received and processed successfully but the client did not
- receive the response, e.g. due to a network error."
- closed
- "You are attempting to append data to an upload session that
- has alread been closed (i.e. committed)."
- not_closed
- "The session must be closed before calling upload_session/finish_batch."
- union UploadSessionFinishError
- lookup_failed UploadSessionLookupError
- "The session arguments are incorrect; the value explains the reason."
- path WriteError
- "Unable to save the uploaded contents to a file."
- too_many_shared_folder_targets
- "The batch request commits files into too many different shared folders.
- Please limit your batch request to files contained in a single shared folder."
- too_many_write_operations
- "There are too many write operations happening in the user's Dropbox. You should
- retry uploading this file."
- # Req/Resp
- struct UploadSessionStartArg
- close Boolean = false
- "If true, the current session will be closed, at which point you won't
- be able to call :route:`upload_session/append_v2` anymore with the
- current session."
- example with_close
- close = false
- struct UploadSessionStartResult
- session_id String
- "A unique identifier for the upload session. Pass this to
- :route:`upload_session/append_v2` and
- :route:`upload_session/finish`."
- example default
- session_id = "1234faaf0678bcde"
- route upload_session/start (UploadSessionStartArg, UploadSessionStartResult, Void)
- "Upload sessions allow you to upload a single file in one or more
- requests, for example where the size of the file is greater than 150
- MB. This call starts a new upload session with the given data. You
- can then use :route:`upload_session/append_v2` to add more data and
- :route:`upload_session/finish` to save all the data to a file in
- Dropbox.
- A single request should not upload more than 150 MB.
- An upload session can be used for a maximum of 48 hours. Attempting
- to use an :field:`UploadSessionStartResult.session_id` with
- :route:`upload_session/append_v2` or :route:`upload_session/finish` more
- than 48 hours after its creation will return a
- :field:`UploadSessionLookupError.not_found`."
- attrs
- host = "content"
- style = "upload"
- owner = "dev-plat"
- feature = "upload_api_rate_limit"
- allow_app_folder_app = true
- struct UploadSessionAppendArg
- cursor UploadSessionCursor
- "Contains the upload session ID and the offset."
- close Boolean = false
- "If true, the current session will be closed, at which point
- you won't be able to call :route:`upload_session/append_v2`
- anymore with the current session."
- example default
- cursor = default
- route upload_session/append_v2 (UploadSessionAppendArg, Void, UploadSessionLookupError)
- "Append more data to an upload session.
- When the parameter close is set, this call will close the session.
- A single request should not upload more than 150 MB."
- attrs
- host = "content"
- style = "upload"
- owner = "dev-plat"
- feature = "upload_api_rate_limit"
- allow_app_folder_app = true
- struct UploadSessionCursor
- session_id String
- "The upload session ID (returned by :route:`upload_session/start`)."
- offset UInt64
- "The amount of data that has been uploaded so far. We use this to make
- sure upload data isn't lost or duplicated in the event of a network
- error."
- example default
- session_id = "1234faaf0678bcde"
- offset = 0
- route upload_session/append (UploadSessionCursor, Void, UploadSessionLookupError) deprecated by upload_session/append_v2
- "Append more data to an upload session.
- A single request should not upload more than 150 MB."
- attrs
- host = "content"
- style = "upload"
- owner = "dev-plat"
- feature = "upload_api_rate_limit"
- allow_app_folder_app = true
- union_closed WriteMode
- "Your intent when writing a file to some path. This is used to determine
- what constitutes a conflict and what the autorename strategy is.
- In some situations, the conflict behavior is identical:
- (a) If the target path doesn't contain anything, the file is always written;
- no conflict.
- (b) If the target path contains a folder, it's always a conflict.
- (c) If the target path contains a file with identical contents, nothing gets
- written; no conflict.
- The conflict checking differs in the case where there's a file at the target
- path with contents different from the contents you're trying to write."
- add
- "Do not overwrite an existing file if there is a conflict. The
- autorename strategy is to append a number to the file name. For example,
- \"document.txt\" might become \"document (2).txt\"."
- overwrite
- "Always overwrite the existing file. The autorename
- strategy is the same as it is for :field:`add`."
- update Rev
- "Overwrite if the given \"rev\" matches the existing file's \"rev\".
- The autorename strategy is to append the string \"conflicted copy\"
- to the file name. For example, \"document.txt\" might become
- \"document (conflicted copy).txt\" or \"document (Panda's conflicted copy).txt\"."
- example default
- add = null
- example overwriting
- overwrite = null
- example with_revision
- update = "a1c10ce0dd78"
- struct CommitInfo
- path WritePath
- "Path in the user's Dropbox to save the file."
- mode WriteMode = add
- "Selects what to do if the file already exists."
- autorename Boolean = false
- "If there's a conflict, as determined by :field:`mode`, have the Dropbox
- server try to autorename the file to avoid conflict."
- client_modified common.DropboxTimestamp?
- "The value to store as the :field:`client_modified` timestamp. Dropbox
- automatically records the time at which the file was written to the
- Dropbox servers. It can also record an additional timestamp, provided
- by Dropbox desktop clients, mobile clients, and API apps of when the
- file was actually created or modified."
- mute Boolean = false
- "Normally, users are made aware of any file modifications in their
- Dropbox account via notifications in the client software. If
- :val:`true`, this tells the clients that this modification shouldn't
- result in a user notification."
- example default
- path = "/Homework/math/Matrices.txt"
- autorename = true
- example update
- path = "/Homework/math/Matrices.txt"
- mode = with_revision
- autorename = false
- struct UploadSessionFinishArg
- cursor UploadSessionCursor
- "Contains the upload session ID and the offset."
- commit CommitInfo
- "Contains the path and other optional modifiers for the commit."
- example default
- cursor = default
- commit = default
- example update
- cursor = default
- commit = update
- route upload_session/finish (UploadSessionFinishArg, FileMetadata, UploadSessionFinishError)
- "Finish an upload session and save the uploaded data to the given file
- path.
- A single request should not upload more than 150 MB."
- attrs
- host = "content"
- style = "upload"
- owner = "dev-plat"
- feature = "upload_api_rate_limit"
- allow_app_folder_app = true
- route upload (CommitInfo, FileMetadata, UploadError)
- "Create a new file with the contents provided in the request.
- Do not use this to upload a file larger than 150 MB. Instead, create an
- upload session with :route:`upload_session/start`."
- attrs
- host = "content"
- style = "upload"
- owner = "dev-plat"
- feature = "upload_api_rate_limit"
- allow_app_folder_app = true
- takes_path_root = true
- #
- # Batch Upload
- #
- struct UploadSessionFinishBatchArg
- entries List(UploadSessionFinishArg, max_items=1000)
- "Commit information for each file in the batch."
- example default
- entries = [default]
- struct UploadSessionFinishBatchResult
- entries List(UploadSessionFinishBatchResultEntry)
- "Commit result for each file in the batch."
- example default
- entries = [default]
- union_closed UploadSessionFinishBatchResultEntry
- success FileMetadata
- failure UploadSessionFinishError
- example default
- success = default
- union_closed UploadSessionFinishBatchJobStatus extends async.PollResultBase
- complete UploadSessionFinishBatchResult
- "The :route:`upload_session/finish_batch` has finished."
- example default
- complete = default
- union UploadSessionFinishBatchLaunch extends async.LaunchResultBase
- "Result returned by :route:`upload_session/finish_batch` that may either launch an
- asynchronous job or complete synchronously."
- complete UploadSessionFinishBatchResult
- example complete
- complete = default
- example async_job_id
- async_job_id = "34g93hh34h04y384084"
- route upload_session/finish_batch (UploadSessionFinishBatchArg, UploadSessionFinishBatchLaunch, Void)
- "This route helps you commit many files at once into a user's Dropbox. Use
- :route:`upload_session/start` and :route:`upload_session/append_v2` to
- upload file contents. We recommend uploading many files in parallel to increase
- throughput. Once the file contents have been uploaded, rather than calling
- :route:`upload_session/finish`, use this route to finish all your upload sessions
- in a single request.
- :field:`UploadSessionStartArg.close` or :field:`UploadSessionAppendArg.close`
- needs to be true for the last
- :route:`upload_session/start` or :route:`upload_session/append_v2` call.
- This route will return a job_id immediately and do the async commit job in background.
- Use :route:`upload_session/finish_batch/check` to check the job status.
- For the same account, this route should be executed serially. That means you should not start
- the next job before current job finishes. We allow up to 1000 entries in a single request."
- attrs
- owner = "dev-plat"
- feature = "upload_api_rate_limit"
- allow_app_folder_app = true
- route upload_session/finish_batch/check(async.PollArg, UploadSessionFinishBatchJobStatus, async.PollError)
- "Returns the status of an asynchronous job for :route:`upload_session/finish_batch`. If
- success, it returns list of result for each entry."
- attrs
- owner = "dev-plat"
- allow_app_folder_app = true
- #
- # Search
- #
- union_closed SearchMode
- filename
- "Search file and folder names."
- filename_and_content
- "Search file and folder names as well as file contents."
- deleted_filename
- "Search for deleted file and folder names."
- example default
- filename_and_content = null
- example name_only
- filename = null
- example deleted_names
- deleted_filename = null
- struct SearchArg
- path PathR
- "The path in the user's Dropbox to search. Should probably be
- a folder."
- query String
- "The string to search for. The search string is split on spaces into
- multiple tokens. For file name searching, the last token is used for
- prefix matching (i.e. \"bat c\" matches \"bat cave\" but not \"batman
- car\")."
- start UInt64 = 0
- "The starting index within the search results (used for paging)."
- max_results UInt64(min_value=1, max_value=1000) = 100
- "The maximum number of search results to return."
- mode SearchMode = filename
- "The search mode (filename, filename_and_content, or deleted_filename).
- Note that searching file content is only available for Dropbox Business
- accounts."
- example default
- path = ""
- query = "prime numbers"
- union_closed SearchMatchType
- "Indicates what type of match was found for a given item."
- filename
- "This item was matched on its file or folder name."
- content
- "This item was matched based on its file contents."
- both
- "This item was matched based on both its contents and its file name."
- example default
- content = null
- struct SearchMatch
- match_type SearchMatchType
- "The type of the match."
- metadata Metadata
- "The metadata for the matched file or folder."
- example default
- match_type = default
- metadata = default
- struct SearchResult
- matches List(SearchMatch)
- "A list (possibly empty) of matches for the query."
- more Boolean
- "Used for paging. If true, indicates there is another page of results
- available that can be fetched by calling :route:`search` again."
- start UInt64
- "Used for paging. Value to set the start argument to when calling
- :route:`search` to fetch the next page of results."
- example default
- matches = [default]
- more = false
- start = 1
- union SearchError
- path LookupError
- route search (SearchArg, SearchResult, SearchError)
- "Searches for files and folders.
- Note: Recent changes may not immediately be reflected in search results due to a short delay in indexing."
- attrs
- owner = "dev-plat"
- allow_app_folder_app = true
- #
- # Errors shared by various operations
- #
- alias MalformedPathError = String? # TODO: Maybe a user_message-like thing?
- union LookupError
- malformed_path MalformedPathError
- not_found
- "There is nothing at the given path."
- not_file
- "We were expecting a file, but the given path refers to something that isn't a file."
- not_folder
- "We were expecting a folder, but the given path refers to something that isn't a folder."
- restricted_content
- "The file cannot be transferred because the content is restricted. For example,
- sometimes there are legal restrictions due to copyright claims."
- union WriteError
- malformed_path MalformedPathError
- conflict WriteConflictError
- "Couldn't write to the target path because there was something in the way."
- no_write_permission
- "The user doesn't have permissions to write to the target location."
- insufficient_space
- "The user doesn't have enough available space (bytes) to write more data."
- disallowed_name
- "Dropbox will not save the file or folder because of its name."
- team_folder
- "This endpoint cannot modify or delete team folders."
- union WriteConflictError
- file
- "There's a file in the way."
- folder
- "There's a folder in the way."
- file_ancestor
- "There's a file at an ancestor path, so we couldn't create the required parent folders."
- #
- # Create folder
- #
- struct CreateFolderArg
- path WritePath
- "Path in the user's Dropbox to create."
- autorename Boolean = false
- "If there's a conflict, have the Dropbox server try to autorename
- the folder to avoid the conflict."
- example default
- path = "/Homework/math"
- union_closed CreateFolderError
- path WriteError
- route create_folder (CreateFolderArg, FolderMetadata, CreateFolderError)
- "Create a folder at a given path."
- attrs
- owner = "dev-plat"
- allow_app_folder_app = true
- #
- # Delete
- #
- struct DeleteArg
- path WritePath
- "Path in the user's Dropbox to delete."
- example delete
- path = "/Homework/math/Prime_Numbers.txt"
- union DeleteError
- path_lookup LookupError
- path_write WriteError
- struct DeleteBatchArg
- entries List(DeleteArg)
- example default
- entries = [delete]
- union_closed DeleteBatchResultEntry
- success DeleteResult
- failure DeleteError
- example default
- success = default
- struct DeleteResult
- metadata Metadata
- example default
- metadata = default
- struct DeleteBatchResult
- entries List(DeleteBatchResultEntry)
- example default
- entries = [default]
- union DeleteBatchError
- too_many_write_operations
- "There are too many write operations in user's Dropbox. Please retry
- this request."
- union DeleteBatchJobStatus extends async.PollResultBase
- complete DeleteBatchResult
- "The batch delete has finished."
- failed DeleteBatchError
- "The batch delete has failed."
- example default
- complete = default
- union DeleteBatchLaunch extends async.LaunchResultBase
- "Result returned by :route:`delete_batch` that may either launch an asynchronous job or complete
- synchronously."
- complete DeleteBatchResult
- example complete
- complete = default
- example async_job_id
- async_job_id = "34g93hh34h04y384084"
- route delete (DeleteArg, Metadata, DeleteError)
- "Delete the file or folder at a given path.
- If the path is a folder, all its contents will be deleted too.
- A successful response indicates that the file or folder was deleted. The returned metadata will
- be the corresponding :type:`FileMetadata` or :type:`FolderMetadata` for the item at time of
- deletion, and not a :type:`DeletedMetadata` object."
- attrs
- owner = "dev-plat"
- allow_app_folder_app = true
- route delete_batch (DeleteBatchArg, DeleteBatchLaunch, Void)
- "Delete multiple files/folders at once.
- This route is asynchronous, which returns a job ID immediately and runs
- the delete batch asynchronously. Use :route:`delete_batch/check` to check
- the job status."
- attrs
- owner = "dev-plat"
- allow_app_folder_app = true
- route delete_batch/check (async.PollArg, DeleteBatchJobStatus, async.PollError)
- "Returns the status of an asynchronous job for :route:`delete_batch`. If
- success, it returns list of result for each entry."
- attrs
- owner = "dev-plat"
- allow_app_folder_app = true
- route permanently_delete (DeleteArg, Void, DeleteError)
- "Permanently delete the file or folder at a given path
- (see https://www.dropbox.com/en/help/40).
- Note: This endpoint is only available for Dropbox Business apps."
- #
- # Args and error shared by copy and move
- #
- struct RelocationPath
- from_path WritePath
- "Path in the user's Dropbox to be copied or moved."
- to_path WritePath
- "Path in the user's Dropbox that is the destination."
- example default
- from_path = "/Homework/math"
- to_path = "/Homework/algebra"
- struct RelocationArg extends RelocationPath
- allow_shared_folder Boolean = false
- "If true, :route:`copy` will copy contents in shared folder,
- otherwise :field:`RelocationError.cant_copy_shared_folder` will be
- returned if :field:`from_path` contains shared folder. This field is
- always true for :route:`move`."
- autorename Boolean = false
- "If there's a conflict, have the Dropbox server try to autorename
- the file to avoid the conflict."
- example default
- from_path = "/Homework/math"
- to_path = "/Homework/algebra"
- union RelocationError
- from_lookup LookupError
- from_write WriteError
- to WriteError
- cant_copy_shared_folder
- "Shared folders can't be copied."
- cant_nest_shared_folder
- "Your move operation would result in nested shared folders. This is not allowed."
- cant_move_folder_into_itself
- "You cannot move a folder into itself."
- too_many_files
- "The operation would involve more than 10,000 files and folders."
- duplicated_or_nested_paths
- "There are duplicated/nested paths among :field:`RelocationArg.from_path`
- and :field:`RelocationArg.to_path`."
- struct RelocationBatchArg
- entries List(RelocationPath)
- "List of entries to be moved or copied. Each entry is :type:`RelocationPath`."
- allow_shared_folder Boolean = false
- "If true, :route:`copy_batch` will copy contents in shared folder,
- otherwise :field:`RelocationError.cant_copy_shared_folder` will be
- returned if :field:`RelocationPath.from_path` contains shared folder.
- This field is always true for :route:`move_batch`."
- autorename Boolean = false
- "If there's a conflict with any file, have the Dropbox server try to
- autorename that file to avoid the conflict."
- example default
- entries = [default]
- struct RelocationBatchResult
- entries List(RelocationResult)
- example default
- entries = [default]
- union_closed RelocationBatchJobStatus extends async.PollResultBase
- complete RelocationBatchResult
- "The copy or move batch job has finished."
- failed RelocationBatchError
- "The copy or move batch job has failed with exception."
- example default
- complete = default
- union RelocationBatchLaunch extends async.LaunchResultBase
- "Result returned by :route:`copy_batch` or :route:`move_batch` that may either launch an
- asynchronous job or complete synchronously."
- complete RelocationBatchResult
- example complete
- complete = default
- example async_job_id
- async_job_id = "34g93hh34h04y384084"
- struct RelocationResult
- metadata Metadata
- example default
- metadata = default
- union RelocationBatchError extends RelocationError
- too_many_write_operations
- "There are too many write operations in user's Dropbox. Please retry
- this request."
- #
- # Copy
- #
- route copy (RelocationArg, Metadata, RelocationError)
- "Copy a file or folder to a different location in the user's Dropbox.
- If the source path is a folder all its contents will be copied."
- attrs
- owner = "dev-plat"
- allow_app_folder_app = true
- route copy_batch (RelocationBatchArg, RelocationBatchLaunch, Void)
- "Copy multiple files or folders to different locations at once in the
- user's Dropbox.
- If :field:`RelocationBatchArg.allow_shared_folder` is false, this
- route is atomic. If on entry failes, the whole transaction will abort. If
- :field:`RelocationBatchArg.allow_shared_folder` is true, not
- atomicity is guaranteed, but you will be able to copy the contents of
- shared folders to new locations.
- This route will return job ID immediately and do the async copy job in
- background. Please use :route:`copy_batch/check` to check the job status."
- attrs
- owner = "dev-plat"
- allow_app_folder_app = true
- route copy_batch/check(async.PollArg, RelocationBatchJobStatus, async.PollError)
- "Returns the status of an asynchronous job for :route:`copy_batch`. If
- success, it returns list of results for each entry."
- attrs
- owner = "dev-plat"
- allow_app_folder_app = true
- #
- # Move
- #
- route move (RelocationArg, Metadata, RelocationError)
- "Move a file or folder to a different location in the user's Dropbox.
- If the source path is a folder all its contents will be moved."
- attrs
- owner = "dev-plat"
- allow_app_folder_app = true
- route move_batch (RelocationBatchArg, RelocationBatchLaunch, Void)
- "Move multiple files or folders to different locations at once in the
- user's Dropbox.
- This route is 'all or nothing', which means if one entry fails, the
- whole transaction will abort.
- This route will return job ID immediately and do the async moving job in
- background. Please use :route:`move_batch/check` to check the job status."
- attrs
- owner = "dev-plat"
- allow_app_folder_app = true
- route move_batch/check(async.PollArg, RelocationBatchJobStatus, async.PollError)
- "Returns the status of an asynchronous job for :route:`move_batch`. If
- success, it returns list of results for each entry."
- attrs
- owner = "dev-plat"
- allow_app_folder_app = true
- #
- # Thumbnail
- #
- union_closed ThumbnailSize
- w32h32
- "32 by 32 px."
- w64h64
- "64 by 64 px."
- w128h128
- "128 by 128 px."
- w640h480
- "640 by 480 px."
- w1024h768
- "1024 by 768."
- union_closed ThumbnailFormat
- jpeg
- png
- struct ThumbnailArg
- path ReadPath
- "The path to the image file you want to thumbnail."
- format ThumbnailFormat = jpeg
- "The format for the thumbnail image, jpeg (default) or png. For
- images that are photos, jpeg should be preferred, while png is
- better for screenshots and digital arts."
- size ThumbnailSize = w64h64
- "The size for the thumbnail image."
- example default
- path = "/image.jpg"
- format = jpeg
- example id
- path = "id:a4ayc_80_OEAAAAAAAAAYa"
- format = jpeg
- example rev
- path = "rev:a1c10ce0dd78"
- format = jpeg
- union_closed ThumbnailError
- path LookupError
- "An error occurs when downloading metadata for the image."
- unsupported_extension
- "The file extension doesn't allow conversion to a thumbnail."
- unsupported_image
- "The image cannot be converted to a thumbnail."
- conversion_error
- "An error occurs during thumbnail conversion."
- route get_thumbnail(ThumbnailArg, FileMetadata, ThumbnailError)
- "Get a thumbnail for an image.
- This method currently supports files with the following file extensions:
- jpg, jpeg, png, tiff, tif, gif and bmp. Photos that are larger than 20MB
- in size won't be converted to a thumbnail."
- attrs
- host = "content"
- style = "download"
- owner = "dev-plat"
- allow_app_folder_app = true
- #
- # Preview
- #
- struct PreviewArg
- path ReadPath
- "The path of the file to preview."
- rev Rev?
- "Deprecated. Please specify revision in :field:`path` instead."
- example default
- path = "/word.docx"
- example id
- path = "id:a4ayc_80_OEAAAAAAAAAYa"
- example rev
- path = "rev:a1c10ce0dd78"
- union_closed PreviewError
- path LookupError
- "An error occurs when downloading metadata for the file."
- in_progress
- "This preview generation is still in progress and the file is not ready
- for preview yet."
- unsupported_extension
- "The file extension is not supported preview generation."
- unsupported_content
- "The file content is not supported for preview generation."
- route get_preview(PreviewArg, FileMetadata, PreviewError)
- "Get a preview for a file.
- Currently, PDF previews are generated for files with the following extensions:
- .ai, .doc, .docm, .docx, .eps, .odp, .odt, .pps, .ppsm, .ppsx, .ppt, .pptm, .pptx, .rtf.
- HTML previews are generated for files with the following extensions: .csv, .ods, .xls, .xlsm, .xlsx.
- Other formats will return an unsupported extension error."
- attrs
- host = "content"
- style = "download"
- owner = "dev-plat"
- allow_app_folder_app = true
- #
- # List revisions
- #
- struct ListRevisionsArg
- path PathOrId
- "The path to the file you want to see the revisions of."
- limit UInt64(min_value=1, max_value=100) = 10
- "The maximum number of revision entries returned."
- # TODO: Add last_rev when we get pagination support from FJ Service.
- example default
- path = "/root/word.docx"
- limit = 10
- union ListRevisionsError
- path LookupError
- struct ListRevisionsResult
- is_deleted Boolean
- "If the file is deleted."
- entries List(FileMetadata)
- "The revisions for the file. Only non-delete revisions will show up here."
- example default
- is_deleted = false
- entries = [default]
- route list_revisions(ListRevisionsArg, ListRevisionsResult, ListRevisionsError)
- "Return revisions of a file."
- attrs
- owner = "dev-plat"
- allow_app_folder_app = true
- #
- # Restore
- #
- struct RestoreArg
- path WritePath
- "The path to the file you want to restore."
- rev Rev
- "The revision to restore for the file."
- example default
- path = "/root/word.docx"
- rev = "a1c10ce0dd78"
- union RestoreError
- path_lookup LookupError
- "An error occurs when downloading metadata for the file."
- path_write WriteError
- "An error occurs when trying to restore the file to that path."
- invalid_revision
- "The revision is invalid. It may point to a different file."
- route restore(RestoreArg, FileMetadata, RestoreError)
- "Restore a file to a specific revision."
- attrs
- owner = "dev-plat"
- allow_app_folder_app = true
- #
- # Temporary link
- #
- struct GetTemporaryLinkArg
- path ReadPath
- "The path to the file you want a temporary link to."
- example default
- path = "/video.mp4"
- struct GetTemporaryLinkResult
- metadata FileMetadata
- "Metadata of the file."
- link String
- "The temporary link which can be used to stream content the file."
- example default
- metadata = default
- link = "https://dl.dropboxusercontent.com/apitl/1/YXNkZmFzZGcyMzQyMzI0NjU2NDU2NDU2"
- union GetTemporaryLinkError
- path LookupError
- route get_temporary_link(GetTemporaryLinkArg, GetTemporaryLinkResult, GetTemporaryLinkError)
- "Get a temporary link to stream content of a file. This link will expire in four hours and
- afterwards you will get 410 Gone. Content-Type of the link is determined automatically by
- the file's mime type."
- attrs
- owner = "dev-plat"
- allow_app_folder_app = true
- #
- # Copy reference
- #
- struct GetCopyReferenceArg
- path ReadPath
- "The path to the file or folder you want to get a copy reference to."
- example default
- path = "/video.mp4"
- struct GetCopyReferenceResult
- metadata Metadata
- "Metadata of the file or folder."
- copy_reference String
- "A copy reference to the file or folder."
- expires common.DropboxTimestamp
- "The expiration date of the copy reference. This value is currently set to be
- far enough in the future so that expiration is effectively not an issue."
- example default
- metadata = default
- copy_reference = "z1X6ATl6aWtzOGq0c3g5Ng"
- expires = "2045-05-12T15:50:38Z"
- union GetCopyReferenceError
- path LookupError
- route copy_reference/get(GetCopyReferenceArg, GetCopyReferenceResult, GetCopyReferenceError)
- "Get a copy reference to a file or folder. This reference string can be used to
- save that file or folder to another user's Dropbox by passing it to
- :route:`copy_reference/save`."
- attrs
- owner = "dev-plat"
- allow_app_folder_app = true
- struct SaveCopyReferenceArg
- copy_reference String
- "A copy reference returned by :route:`copy_reference/get`."
- path Path
- "Path in the user's Dropbox that is the destination."
- example default
- copy_reference = "z1X6ATl6aWtzOGq0c3g5Ng"
- path = "/video.mp4"
- struct SaveCopyReferenceResult
- metadata Metadata
- "The metadata of the saved file or folder in the user's Dropbox."
- example default
- metadata = default
- union SaveCopyReferenceError
- path WriteError
- invalid_copy_reference
- "The copy reference is invalid."
- no_permission
- "You don't have permission to save the given copy reference. Please make sure this app
- is same app which created the copy reference and the source user is still linked to
- the app."
- not_found
- "The file referenced by the copy reference cannot be found."
- too_many_files
- "The operation would involve more than 10,000 files and folders."
- route copy_reference/save(SaveCopyReferenceArg, SaveCopyReferenceResult, SaveCopyReferenceError)
- "Save a copy reference returned by :route:`copy_reference/get` to the user's Dropbox."
- attrs
- owner = "dev-plat"
- allow_app_folder_app = true
- #
- # Save URL
- #
- struct SaveUrlArg
- path Path
- "The path in Dropbox where the URL will be saved to."
- url String
- "The URL to be saved."
- example default
- path = "/a.txt"
- url = "http://example.com/a.txt"
- union_closed SaveUrlResult extends async.LaunchResultBase
- complete FileMetadata
- "Metadata of the file where the URL is saved to."
- union SaveUrlError
- path WriteError
- download_failed
- "Failed downloading the given URL."
- invalid_url
- "The given URL is invalid."
- not_found
- "The file where the URL is saved to no longer exists."
- route save_url(SaveUrlArg, SaveUrlResult, SaveUrlError)
- "Save a specified URL into a file in user's Dropbox. If the given path already
- exists, the file will be renamed to avoid the conflict (e.g. myfile (1).txt)."
- attrs
- owner = "dev-plat"
- allow_app_folder_app = true
- #
- # Save URL Job
- #
- union_closed SaveUrlJobStatus extends async.PollResultBase
- complete FileMetadata
- "Metadata of the file where the URL is saved to."
- failed SaveUrlError
- route save_url/check_job_status(async.PollArg, SaveUrlJobStatus, async.PollError)
- "Check the status of a :route:`save_url` job."
- attrs
- owner = "dev-plat"
- allow_app_folder_app = true
|