Spec Update 05/11/2026 (#81)

Change Notes:

account Namespace:
- Add get_photo route
- Add PhotoSourceArg, SetProfilePhotoArg, SetProfilePhotoError structs

auth Namespace:
- Add token/from_oauth1, token/revoke routes
- Add AccessError, AuthError, InvalidAccountTypeError, RateLimitError structs/unions

check Namespace:
- Update app/check and user/check routes to return EchoError instead of Void

common Namespace:
- Add DropboxDuration struct

file_properties Namespace:
- Remove properties/remove, properties/template/get, properties/template/list routes
- Update Comments

file_requests Namespace:
- Update Comments

files Namespace:
- Add upload_session/append_batch route
- Remove properties/remove, properties/template/get, properties/template/list routes
- Update Comments

paper Namespace:
- Add docs/get_metadata route
- Update Comments

riviera Namespace:
- Add riviera Namespace
- Add get_transcript_async, get_transcript_async/check routes

sharing Namespace:
- Add relinquish_access route
- Add ShareFolderErrorV2, SharePathErrorV2, SharedLinkMetadataError unions
- Update Comments

team Namespace:
- Add members/delete_former_member_files, team_folder/restore routes
- Remove properties/template/list, properties/template/update routes
- Update Comments

team_log Namespace:
- Add ~200 new event detail structs and unions
- Update Comments

team_policies Namespace:
- Add DefaultLinkExpirationDaysPolicy, EnforceLinkPasswordPolicy,
  SharedLinkDefaultPermissionsPolicy, TopLevelContentPolicy unions

users Namespace:
- Update Comments

users_common Namespace:
- Update Comments

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: AndreyVMarkelov

account.stone

@@ -1,10 +1,19 @@
 namespace account
 
+import account_id
 import common
 
-#
-# Route set_profile_photo
-#
+route get_photo (AccountPhotoGetArg, AccountPhotoGetResult, AccountPhotoGetError)
+    "This lovely endpoint gets the account photo of a given user."
+
+    attrs
+        allow_app_folder_app = true
+        auth = "user"
+        host = "content"
+        scope = "account_info.read"
+        select_admin_mode = "whole_team"
+        style = "download"
+
 
 union PhotoSourceArg
     base64_data String
@@ -13,6 +22,17 @@ union PhotoSourceArg
     example default
         base64_data = "SW1hZ2UgZGF0YSBpbiBiYXNlNjQtZW5jb2RlZCBieXRlcy4gTm90IGEgdmFsaWQgZXhhbXBsZS4="
 
+union SetProfilePhotoError
+    file_type_error
+        "File cannot be set as profile photo."
+    file_size_error
+        "File cannot exceed 10 MB."
+    dimension_error
+        "Image must be larger than 128 x 128."
+    thumbnail_error
+        "Image could not be thumbnailed."
+    transient_error
+        "Temporary infrastructure failure, please retry."
 
 struct SetProfilePhotoArg
     photo PhotoSourceArg
@@ -21,29 +41,54 @@ struct SetProfilePhotoArg
     example default
         photo = default
 
-
 struct SetProfilePhotoResult
     profile_photo_url String
         "URL for the photo representing the user, if one is set."
 
     example default
         profile_photo_url = "https://dl-web.dropbox.com/account_photo/get/dbaphid%3AAAHWGmIXV3sUuOmBfTz0wPsiqHUpBWvv3ZA?vers=1556069330102&size=128x128"
 
+struct AccountPhotoGetArg
+    dbx_account_id String
+        "Encoded ID of the user. Must start either with 'dbid:' or 'dbaphid:'."
+    size String
+        "A string representing the size of the photo."
+    circle_crop Boolean
+        "True if the photo should be cropped and false otherwise."
+    expect_account_photo Boolean
+        "True if we expect account photo to exist."
 
-union SetProfilePhotoError
-    file_type_error
-        "File cannot be set as profile photo."
-    file_size_error
-        "File cannot exceed 10 MB."
-    dimension_error
-        "Image must be larger than 128 x 128."
-    thumbnail_error
-        "Image could not be thumbnailed."
-    transient_error
-        "Temporary infrastructure failure, please retry."
+    example default
+        dbx_account_id = "dbid:s0meEnc0ded1d"
+        size = "16x16"
+        circle_crop = false
+        expect_account_photo = true
+
+union ThumbnailError
+    permanent_failure
+        "Indicates permanent infrastructural failure."
+    temporary_failure
+        "Indicates temporary infrastructural failure."
+
+union AccountPhotoGetError
+    thumbnail_error ThumbnailError
+        "Indicates infrastructural failure."
+    account_photo_missing
+        "Account photo is missing (but we did not expect it to exist)."
+    expected_account_photo_missing
+        "Account photo was expected to exist, but it's missing."
 
-route set_profile_photo(SetProfilePhotoArg, SetProfilePhotoResult, SetProfilePhotoError)
+struct AccountPhotoGetResult
+    content_type String
+        "The data returned by get_photo."
+
+    example default
+        content_type = "image/jpeg"
+
+route set_profile_photo (SetProfilePhotoArg, SetProfilePhotoResult, SetProfilePhotoError)
     "Sets a user's profile photo."
 
     attrs
+        auth = "user"
         scope = "account_info.write"
+

account_id.stone

@@ -0,0 +1,6 @@
+namespace account_id
+
+annotation_type ContainsDbidAnnotation
+    "Annotation type should be applied to Response object fields which contain account id"
+
+    authorize_caller Boolean = true

async.stone

@@ -1,31 +1,15 @@
 namespace async
 
-#
-# Types for writing asynchronous API methods.
-#
-# There are two calls for each asynchronous method:
-#  1. A "Launch" method that (optionally) launches the asynchronous job
-#  2. A "Polling" method that polls for the status of the job that was launched by the first call.
-#
-# The following definitions are prefixed by "Launch" or "Poll", according to their intended use.
-
+import common
 
 alias AsyncJobId = String(min_length=1)
 
-
-#
-# Launch
-#
-
 union_closed LaunchResultBase
     "Result returned by methods that launch an asynchronous job.
-
     A method who may either launch an asynchronous job, or complete the request
     synchronously, can use this union by extending it, and adding a 'complete' field
     with the type of the synchronous response.
-
     See :type:`LaunchEmptyResult` for an example."
-
     async_job_id AsyncJobId
         "This response indicates that the processing is asynchronous.
         The string is an id that can be used to obtain the status of the asynchronous job."
@@ -36,63 +20,50 @@ union_closed LaunchResultBase
 union_closed LaunchEmptyResult extends LaunchResultBase
     "Result returned by methods that may either launch an asynchronous job or complete synchronously.
     Upon synchronous completion of the job, no additional information is returned."
-
     complete
         "The job finished synchronously and successfully."
 
     example complete
         complete = null
-
+    
     example async_job_id
         async_job_id = "34g93hh34h04y384084"
 
-#
-# Poll
-#
-
 struct PollArg
     "Arguments for methods that poll the status of an asynchronous job."
-
     async_job_id AsyncJobId
         "Id of the asynchronous job.
         This is the value of a response returned from the method that launched the job."
 
     example default
         async_job_id = "34g93hh34h04y384084"
 
-# TODO(kelkabany): Remove `error_msg` since others might want to return it
-# differently.
 union_closed PollResultBase
     "Result returned by methods that poll for the status of an asynchronous job.
     Unions that extend this union should add a 'complete' field with a type of
     the information returned upon job completion.
-
-    See :type:`PollEmptyResult` for an example."
-
+    See :type:`PollEmptyResult` for an example"
     in_progress
         "The asynchronous job is still in progress."
 
-
 union_closed PollEmptyResult extends PollResultBase
     "Result returned by methods that poll for the status of an asynchronous job.
     Upon completion of the job, no additional information is returned."
-
     complete
         "The asynchronous job has completed successfully."
 
     example complete
         complete = null
-
+    
     example in_progress
         in_progress = null
 
-
 union PollError
     "Error returned by methods for polling the status of asynchronous job."
-
     invalid_async_job_id
         "The job ID is invalid."
     internal_error
         "Something went wrong with the job on Dropbox's end. You'll need to
         verify that the action you were taking succeeded, and if not, try
         again. This should happen very rarely."
+

auth.stone

@@ -2,13 +2,8 @@ namespace auth
 
 import common
 
-struct TokenScopeError
-    required_scope String
-        "The required scope to access the route."
-
 union AuthError
     "Errors occurred during authentication."
-
     invalid_access_token
         "The access token is invalid."
     invalid_select_user
@@ -24,39 +19,60 @@ union AuthError
     route_access_denied
         "The route is not available to public."
 
-route token/revoke(Void, Void, Void)
-    "Disables the access token used to authenticate the call.
-    If there is a corresponding refresh token for the access token,
-    this disables that refresh token, as well as any other access tokens for that refresh token."
-
-    attrs
-        allow_app_folder_app = true
-
 union RateLimitReason
     too_many_requests
         "You are making too many requests in the past few minutes."
     too_many_write_operations
         "There are currently too many write operations happening in the user's Dropbox."
 
+union TokenFromOAuth1Error
+    invalid_oauth1_token_info
+        "Part or all of the OAuth 1.0 access token info is invalid."
+    app_id_mismatch
+        "The authorized app does not match the app associated with the supplied access token."
+
+union AccessError
+    "Error occurred because the account doesn't have permission to access the resource."
+    invalid_account_type InvalidAccountTypeError
+        "Current account type cannot access the resource."
+    paper_access_denied PaperAccessError
+        "Current account cannot access Paper."
+    team_access_denied
+        "Team doesn't have permission to access."
+    no_permission NoPermissionError
+        "Caller does not have permission to access the resource."
+
+union PaperAccessError
+    paper_disabled
+        "Paper is disabled."
+    not_paper_user
+        "The provided user has not used Paper yet."
+
+union InvalidAccountTypeError
+    endpoint
+        "Current account type doesn't have permission to access this route endpoint."
+    feature
+        "Current account type doesn't have permission to access this feature."
+
+union NoPermissionError
+    unauthorized_account_id_usage UnauthorizedAccountIdUsageError
+        "Current caller does not have permission to access the account information for one or more of the specified account IDs."
+
+struct TokenScopeError
+    required_scope String
+        "The required scope to access the route."
+
 struct RateLimitError
     "Error occurred because the app is being rate limited."
-
     reason RateLimitReason
         "The reason why the app is being rate limited."
-
     retry_after UInt64 = 1
         "The number of seconds that the app should wait
         before making another request."
 
-#
-# OAuth 1.0 token conversion
-#
-
 struct TokenFromOAuth1Arg
-
     oauth1_token String(min_length=1)
         "The supplied OAuth 1.0 access token."
-
     oauth1_token_secret String(min_length=1)
         "The token secret associated with the supplied access token."
 
@@ -65,42 +81,29 @@ struct TokenFromOAuth1Arg
         oauth1_token_secret = "qomoftv0472git7"
 
 struct TokenFromOAuth1Result
-
     oauth2_token String(min_length=1)
         "The OAuth 2.0 token generated from the supplied OAuth 1.0 token."
 
     example default
         oauth2_token = "9mCrkS7BIdAAAAAAAAAAHHS0TsSnpYvKQVtKdBnN5IuzhYOGblSgTcHgBFKFMmFn"
 
-union TokenFromOAuth1Error
-    invalid_oauth1_token_info
-        "Part or all of the OAuth 1.0 access token info is invalid."
-    app_id_mismatch
-        "The authorized app does not match the app associated with the supplied access token."
+struct UnauthorizedAccountIdUsageError
+    unauthorized_account_ids List(String)
+        "The account IDs that the caller does not have permission to use."
+
+route token/revoke (Void, Void, Void)
+    "Disables the access token used to authenticate the call.
+    If there is a corresponding refresh token for the access token,
+    this disables that refresh token, as well as any other access tokens for that refresh token."
 
-route token/from_oauth1(TokenFromOAuth1Arg, TokenFromOAuth1Result, TokenFromOAuth1Error) deprecated
-    "Creates an OAuth 2.0 access token from the supplied OAuth 1.0 access token."
     attrs
-        auth = "app"
         allow_app_folder_app = true
+        auth = "user"
 
-union AccessError
-    "Error occurred because the account doesn't have permission to access the resource."
-
-    invalid_account_type InvalidAccountTypeError
-        "Current account type cannot access the resource."
-
-    paper_access_denied PaperAccessError
-        "Current account cannot access Paper."
+route token/from_oauth1 (TokenFromOAuth1Arg, TokenFromOAuth1Result, TokenFromOAuth1Error) deprecated
+    "Creates an OAuth 2.0 access token from the supplied OAuth 1.0 access token."
 
-union PaperAccessError
-    paper_disabled
-        "Paper is disabled."
-    not_paper_user
-        "The provided user has not used Paper yet."
+    attrs
+        allow_app_folder_app = true
+        auth = "app"
 
-union InvalidAccountTypeError
-    endpoint
-        "Current account type doesn't have permission to access this route endpoint."
-    feature
-        "Current account type doesn't have permission to access this feature."