> 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 Workspace Edit POST https://api.dropboxapi.com/2/agent_filesystem/agents/workspace/edit Content-Type: application/json Adds, replaces, or removes explicit file or folder rules in an agent's workspace. Rules for items not included in the request remain unchanged. Each referenced item must already exist and be visible to the authenticated user. **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-workspace-edit ## 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.EditAgentWorkspaceArg. - `agent` (agent_filesystem.AgentSelector, required) — Agent whose workspace is edited. - `entries` (list of agent_filesystem.WorkspaceAccessEdit, required) — Edits to apply. Each entry adds, replaces, or removes the explicit rule for its file or folder. Rules for unmentioned items remain unchanged. ## Response ### 200 Successful response - `entries` (list of agent_filesystem.WorkspaceAccess, required) — Explicit file and folder access rules assigned to the agent. ## 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` (2AgentFilesystemAgentsWorkspaceEditPostResponsesContentApplicationJsonSchemaUserMessage, 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.WorkspaceAccessEdit A file or folder access edit to apply to an agent's workspace. - `path` (string, required) — Existing Dropbox file or folder path, `id:` value, or path relative to a Dropbox namespace. Use "" for the root; "/" is not accepted. The item must be visible to the authenticated user when adding or changing access. Otherwise the request fails with `not_found`. REMOVE also accepts an ID for a deleted or no longer visible item. - `role` (agent_filesystem.WorkspaceRoleRequest, required) — Role to upsert, or REMOVE to delete the item's explicit rule. ### agent_filesystem.WorkspaceAccess An access rule in an agent's workspace. - `role` (agent_filesystem.WorkspaceRole, required) — Maximum access the agent has at this file or folder. - `file_id` (string, optional, nullable) — Canonical Dropbox file or folder ID in `id:` form. Absent for the root rule, which is identified by the empty path. - `path` (string, optional, nullable) — Current root-relative path of the file or folder. The root is "". Absent when the item has been deleted or is no longer visible. Its rule can still be removed using file_id. ### 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 ### 2AgentFilesystemAgentsWorkspaceEditPostResponsesContentApplicationJsonSchemaUserMessage - `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. ### agent_filesystem.WorkspaceRoleRequest Maximum workspace access at a file or folder. A file rule applies only to that file. A folder rule also applies to its descendants until a more specific rule is encountered. Access is denied when no rule matches. - `.tag` (enum, required) - Allowed values: `remove`, `none`, `read`, `read_write` ### agent_filesystem.WorkspaceRole Maximum workspace access at a file or folder. A file rule applies only to that file. A folder rule also applies to its descendants until a more specific rule is encountered. Access is denied when no rule matches. - `.tag` (enum, required) - Allowed values: `remove`, `none`, `read`, `read_write`, `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 ### 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" }, "entries": [ { "path": "string", "role": { ".tag": "remove" } } ] } ``` **Response** ```json { "entries": [ { "role": { ".tag": "remove" }, "file_id": "string", "path": "string" } ] } ``` **SDK Code** ```python import requests url = "https://api.dropboxapi.com/2/agent_filesystem/agents/workspace/edit" payload = { "agent": { ".tag": "agent_id", "agent_id": "string" }, "entries": [ { "path": "string", "role": { ".tag": "remove" } } ] } 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/workspace/edit'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"agent":{".tag":"agent_id","agent_id":"string"},"entries":[{"path":"string","role":{".tag":"remove"}}]}' }; 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/workspace/edit" payload := strings.NewReader("{\n \"agent\": {\n \".tag\": \"agent_id\",\n \"agent_id\": \"string\"\n },\n \"entries\": [\n {\n \"path\": \"string\",\n \"role\": {\n \".tag\": \"remove\"\n }\n }\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/workspace/edit") 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 \"entries\": [\n {\n \"path\": \"string\",\n \"role\": {\n \".tag\": \"remove\"\n }\n }\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/workspace/edit") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"agent\": {\n \".tag\": \"agent_id\",\n \"agent_id\": \"string\"\n },\n \"entries\": [\n {\n \"path\": \"string\",\n \"role\": {\n \".tag\": \"remove\"\n }\n }\n ]\n}") .asString(); ``` ```php request('POST', 'https://api.dropboxapi.com/2/agent_filesystem/agents/workspace/edit', [ 'body' => '{ "agent": { ".tag": "agent_id", "agent_id": "string" }, "entries": [ { "path": "string", "role": { ".tag": "remove" } } ] }', '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/workspace/edit"); 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 \"entries\": [\n {\n \"path\": \"string\",\n \"role\": {\n \".tag\": \"remove\"\n }\n }\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" ], "entries": [ [ "path": "string", "role": [".tag": "remove"] ] ] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.dropboxapi.com/2/agent_filesystem/agents/workspace/edit")! 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() ```