> This page is for Agent Filesystem. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.dropboxapi.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.dropboxapi.com/_mcp/server. # Agents Mutations List POST https://api.dropboxapi.com/2/agent_filesystem/agents/mutations/list Content-Type: application/json Lists retained filesystem mutations performed by the selected agent, newest first. The agent must belong to the authenticated user and Provider app. Pass next_cursor to continue. A move or rename shows the old and new locations in one mutation. When a folder is moved, renamed, or deleted, changes to its contents caused by that operation are not listed separately. **Required scope:** `private:agent_filesystem.agents.manage` **Endpoint format:** [RPC](https://docs.dropboxapi.com/dropbox-api/docs/technical-reference/request-response-formats#rpc-endpoints) **Authentication:** [User](https://docs.dropboxapi.com/dropbox-api/docs/auth-types#user-authentication) This endpoint does not support apps with the app folder permission. Reference: https://docs.dropboxapi.com/agentfs/api-reference/agent-filesystem/agents-mutations-list ## Authentication - `Authorization` header (bearer token, required) — OAuth 2.0 token issued to a specific user. Use `Authorization: Bearer `. Public clients should use the authorization code flow with PKCE (S256). For background or offline access, send `token_access_type=offline` during authorization and use the returned refresh token to obtain new access tokens. You can generate a short-lived access token from the App Console; see [Testing with a generated token](https://docs.dropboxapi.com/dropbox-api/docs/oauth#testing-with-a-generated-token). ## Request ### Headers - `Dropbox-API-Select-User` (string, optional) — Acts on behalf of a team member for supported user-auth operations. Pass a team member ID such as `dbmid:...`. When used with a team token, that token must also include the `team_data.member` scope. - `Dropbox-API-Path-Root` (string, optional) — Scopes path-based operations to a namespace (root). The value is a JSON serialization of the `common.PathRoot` union: `{".tag": "home"}`, `{".tag": "root", "root": ""}`, or `{".tag": "namespace_id", "namespace_id": ""}`. On failure the request returns 422 with a `common.PathRootError`. ### Body (application/json) This endpoint expects an agent_filesystem.ListAgentMutationsArg. - `agent` (agent_filesystem.AgentSelector, required) — Agent whose mutations are listed, across all of its runtime tokens. - `cursor` (string, optional, nullable) — Continuation returned by the preceding call for the same agent. - `limit` (uint, optional, nullable) — Requested page size. Defaults to 100. Pages may exceed this size so that a move or folder operation is not split across pages. ## Response ### 200 Successful response - `mutations` (list of agent_filesystem.Mutation, required) — Mutations in this page, with operation-specific metadata and timestamp_us, a Unix timestamp in microseconds. Precision can be as coarse as one second, so mutations in the same second may share a timestamp. Using it as restore_to_timestamp_us may undo the selected mutation as well as later writes. - `next_cursor` (string, optional, nullable) — Present when another page is available. Cursors expire after 24 hours. ## Errors ### 401 Unauthorized Error Bad or expired token - `error` (auth_apiv2.AuthError, required) — Errors occurred during authentication. - `error_summary` (string, required) — A human-readable summary of the error. ### 403 Forbidden Error The user or team account doesn't have access to the endpoint or feature - `error` (auth_apiv2.AccessError, required) — Error occurred because the account doesn't have permission to access the resource. - `error_summary` (string, required) — A human-readable summary of the error. ### 409 Conflict Error Endpoint-specific error - `error` (agent_filesystem.AgentFsError, required) — Errors specific to Agent Filesystem resources. Authentication, rate-limit, and service errors use the standard API error response. - `error_summary` (string, required) — A human-readable summary of the error. - `user_message` (2AgentFilesystemAgentsMutationsListPostResponsesContentApplicationJsonSchemaUserMessage, optional) ### 429 Too Many Requests Error The app is making too many requests for the given user or team and is being rate limited. The app should wait for the number of seconds specified in the "Retry-After" response header before trying again. - `error` (auth_apiv2.RateLimitError, required) — Error occurred because the app is being rate limited. - `error_summary` (string, required) — A human-readable summary of the error. ### 500 Internal Server Error Internal server error. An error occurred on the Dropbox servers. Check https://status.dropbox.com/ for announcements about Dropbox service issues. - `any` ## Types ### agent_filesystem.AgentSelector Identifies one of the authenticated user's agents by its Agent Filesystem ID. - agent_filesystem.AgentSelector.agent_id: agent_filesystem.AgentSelector.agent_id ### agent_filesystem.Mutation A filesystem mutation performed by the selected agent. - `object_metadata` (AgentFilesystemMutationObjectMetadata, optional, nullable) - `op_type` (agent_filesystem.MutationType, optional) — Operation type. - `timestamp_us` (uint64, optional) — Approximate time of the mutation, in Unix microseconds. ### auth_apiv2.AuthError Errors occurred during authentication. - auth_apiv2.AuthError.invalid_access_token: auth_apiv2.AuthError.invalid_access_token - auth_apiv2.AuthError.invalid_select_user: auth_apiv2.AuthError.invalid_select_user - auth_apiv2.AuthError.invalid_select_admin: auth_apiv2.AuthError.invalid_select_admin - auth_apiv2.AuthError.user_suspended: auth_apiv2.AuthError.user_suspended - auth_apiv2.AuthError.expired_access_token: auth_apiv2.AuthError.expired_access_token - auth_apiv2.AuthError.missing_scope: auth_apiv2.AuthError.missing_scope - auth_apiv2.AuthError.route_access_denied: auth_apiv2.AuthError.route_access_denied - Other: auth_apiv2.AuthError.other ### auth_apiv2.AccessError Error occurred because the account doesn't have permission to access the resource. - auth_apiv2.AccessError.invalid_account_type: auth_apiv2.AccessError.invalid_account_type - auth_apiv2.AccessError.paper_access_denied: auth_apiv2.AccessError.paper_access_denied - auth_apiv2.AccessError.team_access_denied: auth_apiv2.AccessError.team_access_denied - auth_apiv2.AccessError.no_permission: auth_apiv2.AccessError.no_permission - Other: auth_apiv2.AccessError.other ### agent_filesystem.AgentFsError Errors specific to Agent Filesystem resources. Authentication, rate-limit, and service errors use the standard API error response. - agent_filesystem.AgentFsError.not_found: agent_filesystem.AgentFsError.not_found - agent_filesystem.AgentFsError.invalid_input: agent_filesystem.AgentFsError.invalid_input - agent_filesystem.AgentFsError.no_permission: agent_filesystem.AgentFsError.no_permission - agent_filesystem.AgentFsError.conflict: agent_filesystem.AgentFsError.conflict - agent_filesystem.AgentFsError.invalid_cursor: agent_filesystem.AgentFsError.invalid_cursor - Other: agent_filesystem.AgentFsError.other ### 2AgentFilesystemAgentsMutationsListPostResponsesContentApplicationJsonSchemaUserMessage - `locale` (string, optional) - `text` (string, optional) ### auth_apiv2.RateLimitError Error occurred because the app is being rate limited. - `reason` (auth_apiv2.RateLimitReason, required) — The reason why the app is being rate limited. - `retry_after` (uint64, optional, default: 1) — The number of seconds that the app should wait before making another request. ### agent_filesystem.AgentSelector.agent_id Selects the agent by its Agent Filesystem ID. - `.tag` (enum, required) - Allowed values: `agent_id` - `agent_id` (string, required) — Opaque identifier for an agent. Treat this value as case-sensitive and do not parse it. ### AgentFilesystemMutationObjectMetadata - AgentFilesystemMutationObjectMetadata0 - AgentFilesystemMutationObjectMetadata1 - AgentFilesystemMutationObjectMetadata2 - AgentFilesystemMutationObjectMetadata3 - AgentFilesystemMutationObjectMetadata4 - AgentFilesystemMutationObjectMetadata5 - AgentFilesystemMutationObjectMetadata6 - Other: Other ### agent_filesystem.MutationType Operation performed on a file or folder. - `.tag` (enum, required) - Allowed values: `unknown`, `edit`, `add`, `delete`, `move`, `rename`, `move_in`, `move_out`, `mount`, `unmount`, `lost_access`, `share`, `unshare`, `restore`, `restore_version`, `rollback`, `other` ### auth_apiv2.AuthError.invalid_access_token The access token is invalid. This can happen if the access token has been revoked by Dropbox or the user. To fix this, you should re-authenticate the user. Note: Access tokens that are not returned exactly as provisioned will return this error. Be sure not to truncate or otherwise malform access tokens provided by Dropbox. - `.tag` (enum, required) - Allowed values: `invalid_access_token` ### auth_apiv2.AuthError.invalid_select_user The user specified in 'Dropbox-API-Select-User' is no longer on the team. - `.tag` (enum, required) - Allowed values: `invalid_select_user` ### auth_apiv2.AuthError.invalid_select_admin The user specified in 'Dropbox-API-Select-Admin' is not a Dropbox Business team admin. - `.tag` (enum, required) - Allowed values: `invalid_select_admin` ### auth_apiv2.AuthError.user_suspended The user has been suspended. - `.tag` (enum, required) - Allowed values: `user_suspended` ### auth_apiv2.AuthError.expired_access_token The access token has expired. - `.tag` (enum, required) - Allowed values: `expired_access_token` ### auth_apiv2.AuthError.missing_scope The access token does not have the required scope to access the route. - `.tag` (enum, required) - Allowed values: `missing_scope` - `required_scope` (string, required) — The required scope to access the route. ### auth_apiv2.AuthError.route_access_denied The route is not available to public. - `.tag` (enum, required) - Allowed values: `route_access_denied` ### auth_apiv2.AuthError.other An open-union catch-all: a variant added to this union after your API client's spec was generated. Its ".tag" is a value not listed among the known variants above; treat it as an unrecognized/forward-compatible case. - `.tag` (string, optional) ### auth_apiv2.AccessError.invalid_account_type Current account type cannot access the resource. - `.tag` (enum, required) - Allowed values: `invalid_account_type` - `invalid_account_type` (auth_apiv2.InvalidAccountTypeError, required) ### auth_apiv2.AccessError.paper_access_denied Current account cannot access Paper. - `.tag` (enum, required) - Allowed values: `paper_access_denied` - `paper_access_denied` (auth_apiv2.PaperAccessError, required) ### auth_apiv2.AccessError.team_access_denied Team doesn't have permission to access. - `.tag` (enum, required) - Allowed values: `team_access_denied` ### auth_apiv2.AccessError.no_permission Caller does not have permission to access the resource. - `.tag` (enum, required) - Allowed values: `no_permission` - `no_permission` (auth_apiv2.NoPermissionError, required) ### auth_apiv2.AccessError.other An open-union catch-all: a variant added to this union after your API client's spec was generated. Its ".tag" is a value not listed among the known variants above; treat it as an unrecognized/forward-compatible case. - `.tag` (string, optional) ### agent_filesystem.AgentFsError.not_found The requested resource does not exist or is not available to the caller. - `.tag` (enum, required) - Allowed values: `not_found` ### agent_filesystem.AgentFsError.invalid_input One or more request fields are invalid. - `.tag` (enum, required) - Allowed values: `invalid_input` ### agent_filesystem.AgentFsError.no_permission The caller is not allowed to perform the requested operation. - `.tag` (enum, required) - Allowed values: `no_permission` ### agent_filesystem.AgentFsError.conflict The operation conflicts with the resource's current state. - `.tag` (enum, required) - Allowed values: `conflict` ### agent_filesystem.AgentFsError.invalid_cursor The supplied pagination cursor cannot be used for this request. - `.tag` (enum, required) - Allowed values: `invalid_cursor` ### agent_filesystem.AgentFsError.other An open-union catch-all: a variant added to this union after your API client's spec was generated. Its ".tag" is a value not listed among the known variants above; treat it as an unrecognized/forward-compatible case. - `.tag` (string, optional) ### auth_apiv2.RateLimitReason - auth_apiv2.RateLimitReason.too_many_requests: auth_apiv2.RateLimitReason.too_many_requests - auth_apiv2.RateLimitReason.too_many_write_operations: auth_apiv2.RateLimitReason.too_many_write_operations - Other: auth_apiv2.RateLimitReason.other ### AgentFilesystemMutationObjectMetadata0 Details of edits to a file or folder. - `.tag` (enum, required) - Allowed values: `edit_metadata` - `containing_path` (string, optional) — Path of the folder containing the edited item. - `edit_count` (uint, optional) — Number of edits represented by this mutation. - `is_dir` (boolean, optional) — Whether the edited item is a folder. - `name` (string, optional) — Name of the edited file or folder. ### AgentFilesystemMutationObjectMetadata1 Details of a move whose destination is not visible. - `.tag` (enum, required) - Allowed values: `move_out_metadata` - `contents_count` (uint, optional) — Number of files and folders inside the folder. Not currently populated. - `from_containing_path` (string, optional) — Path of the folder that previously contained the item. - `is_dir` (boolean, optional) — Whether the moved item is a folder. - `name` (string, optional) — Name of the moved file or folder. ### AgentFilesystemMutationObjectMetadata2 Details of a move whose source is not visible. - `.tag` (enum, required) - Allowed values: `move_in_metadata` - `contents_count` (uint, optional) — Number of files and folders inside the folder. Not currently populated. - `is_dir` (boolean, optional) — Whether the moved item is a folder. - `name` (string, optional) — Name of the moved file or folder. - `to_containing_path` (string, optional) — Path of the folder that now contains the item. ### AgentFilesystemMutationObjectMetadata3 Details of a move with both locations visible. - `.tag` (enum, required) - Allowed values: `move_metadata` - `contents_count` (uint, optional) — Number of files and folders inside the folder. Not currently populated. - `from_containing_path` (string, optional) — Path of the folder that previously contained the item. - `is_dir` (boolean, optional) — Whether the moved item is a folder. - `name` (string, optional) — Name of the moved file or folder. - `to_containing_path` (string, optional) — Path of the folder that now contains the item. ### AgentFilesystemMutationObjectMetadata4 Details of a rename. - `.tag` (enum, required) - Allowed values: `rename_metadata` - `containing_path` (string, optional) — Path of the folder containing the renamed item. - `contents_count` (uint, optional) — Number of files and folders inside the folder. Not currently populated. - `from_name` (string, optional) — Previous name. - `is_dir` (boolean, optional) — Whether the renamed item is a folder. - `to_name` (string, optional) — New name. ### AgentFilesystemMutationObjectMetadata5 Details of another operation on one file or folder. - `.tag` (enum, required) - Allowed values: `single_object_metadata` - `containing_path` (string, optional) — Path of the folder containing the affected item. - `contents_count` (uint, optional) — Number of files and folders inside the folder. Not currently populated. - `is_dir` (boolean, optional) — Whether the affected item is a folder. - `name` (string, optional) — Name of the affected file or folder. ### AgentFilesystemMutationObjectMetadata6 Details of a restore that rolled back writes to a file or folder. - `.tag` (enum, required) - Allowed values: `rollback_metadata` - `containing_path` (string, optional) — Path of the folder containing the restored item. - `contents_count` (uint, optional) — Number of files and folders affected by the restore. Not currently populated. - `name` (string, optional) — Name of the restored file or folder. - `to_timestamp` (uint64, optional) — Time to which the file or folder was restored. ### Other An open-union catch-all: a variant added to this union after your API client's spec was generated. Its ".tag" is a value not listed among the known variants above; treat it as an unrecognized/forward-compatible case. - `.tag` (string, required) ### auth_apiv2.InvalidAccountTypeError - auth_apiv2.InvalidAccountTypeError.endpoint: auth_apiv2.InvalidAccountTypeError.endpoint - auth_apiv2.InvalidAccountTypeError.feature: auth_apiv2.InvalidAccountTypeError.feature - Other: auth_apiv2.InvalidAccountTypeError.other ### auth_apiv2.PaperAccessError - auth_apiv2.PaperAccessError.paper_disabled: auth_apiv2.PaperAccessError.paper_disabled - auth_apiv2.PaperAccessError.not_paper_user: auth_apiv2.PaperAccessError.not_paper_user - Other: auth_apiv2.PaperAccessError.other ### auth_apiv2.NoPermissionError - auth_apiv2.NoPermissionError.unauthorized_account_id_usage: auth_apiv2.NoPermissionError.unauthorized_account_id_usage - Other: auth_apiv2.NoPermissionError.other ### auth_apiv2.RateLimitReason.too_many_requests You are making too many requests in the past few minutes. - `.tag` (enum, required) - Allowed values: `too_many_requests` ### auth_apiv2.RateLimitReason.too_many_write_operations There are currently too many write operations happening in the user's Dropbox. - `.tag` (enum, required) - Allowed values: `too_many_write_operations` ### auth_apiv2.RateLimitReason.other An open-union catch-all: a variant added to this union after your API client's spec was generated. Its ".tag" is a value not listed among the known variants above; treat it as an unrecognized/forward-compatible case. - `.tag` (string, optional) ### auth_apiv2.InvalidAccountTypeError.endpoint Current account type doesn't have permission to access this endpoint. - `.tag` (enum, required) - Allowed values: `endpoint` ### auth_apiv2.InvalidAccountTypeError.feature Current account type doesn't have permission to access this feature. - `.tag` (enum, required) - Allowed values: `feature` ### auth_apiv2.InvalidAccountTypeError.other An open-union catch-all: a variant added to this union after your API client's spec was generated. Its ".tag" is a value not listed among the known variants above; treat it as an unrecognized/forward-compatible case. - `.tag` (string, optional) ### auth_apiv2.PaperAccessError.paper_disabled Paper is disabled. - `.tag` (enum, required) - Allowed values: `paper_disabled` ### auth_apiv2.PaperAccessError.not_paper_user The provided user has not used Paper yet. - `.tag` (enum, required) - Allowed values: `not_paper_user` ### auth_apiv2.PaperAccessError.other An open-union catch-all: a variant added to this union after your API client's spec was generated. Its ".tag" is a value not listed among the known variants above; treat it as an unrecognized/forward-compatible case. - `.tag` (string, optional) ### auth_apiv2.NoPermissionError.unauthorized_account_id_usage Current caller does not have permission to access the account information for one or more of the specified account IDs. - `.tag` (enum, required) - Allowed values: `unauthorized_account_id_usage` - `unauthorized_account_ids` (list of string, required) — The account IDs that the caller does not have permission to use. ### auth_apiv2.NoPermissionError.other An open-union catch-all: a variant added to this union after your API client's spec was generated. Its ".tag" is a value not listed among the known variants above; treat it as an unrecognized/forward-compatible case. - `.tag` (string, optional) ## Examples **Request** ```json { "agent": { ".tag": "agent_id", "agent_id": "string" } } ``` **Response** ```json { "mutations": [ { "object_metadata": { ".tag": "edit_metadata", "containing_path": "string", "edit_count": 1, "is_dir": true, "name": "string" }, "op_type": { ".tag": "unknown" }, "timestamp_us": 1 } ], "next_cursor": "string" } ``` **SDK Code** ```python import requests url = "https://api.dropboxapi.com/2/agent_filesystem/agents/mutations/list" payload = { "agent": { ".tag": "agent_id", "agent_id": "string" } } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.dropboxapi.com/2/agent_filesystem/agents/mutations/list'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"agent":{".tag":"agent_id","agent_id":"string"}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.dropboxapi.com/2/agent_filesystem/agents/mutations/list" payload := strings.NewReader("{\n \"agent\": {\n \".tag\": \"agent_id\",\n \"agent_id\": \"string\"\n }\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.dropboxapi.com/2/agent_filesystem/agents/mutations/list") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"agent\": {\n \".tag\": \"agent_id\",\n \"agent_id\": \"string\"\n }\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.dropboxapi.com/2/agent_filesystem/agents/mutations/list") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"agent\": {\n \".tag\": \"agent_id\",\n \"agent_id\": \"string\"\n }\n}") .asString(); ``` ```php request('POST', 'https://api.dropboxapi.com/2/agent_filesystem/agents/mutations/list', [ 'body' => '{ "agent": { ".tag": "agent_id", "agent_id": "string" } }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.dropboxapi.com/2/agent_filesystem/agents/mutations/list"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"agent\": {\n \".tag\": \"agent_id\",\n \"agent_id\": \"string\"\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = ["agent": [ ".tag": "agent_id", "agent_id": "string" ]] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.dropboxapi.com/2/agent_filesystem/agents/mutations/list")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```