---
title: "Rename or move a file in the same mailbox"
method: POST
path: "/v1/mailboxes/{mailbox_id}/files/{file_id}/rename"
tags: ["Files"]
---

# Rename or move a file in the same mailbox

`POST /v1/mailboxes/{mailbox_id}/files/{file_id}/rename`

## Request

- Base URL: `https://api.revdoku.com`
- URL: `https://api.revdoku.com/v1/mailboxes/{mailbox_id}/files/{file_id}/rename`
- Auth: HTTP bearer

Changes the path without uploading the content again.

## Path parameters

- `mailbox_id` string, required
- `file_id` string, required

## Request body

- object
  - `new_path` string, required
  - `account_id` string: Select another granted account for this request.
  - `reason` string, nullable: Optional purpose for this action. AI agents should explain intentional reads and changes when known; omit when unknown. Do not include secrets, file contents, or transcripts.

## Response `200`

Success

- object
  - `success` true, required
  - `data` PathOperationResult, required
    - `operation` 'rename' | 'move' | 'copy', required
    - `skipped` boolean, required: True when the file already had the requested path.
    - `old_path` string
    - `path` string, required
    - `source_mailbox_id` string
    - `target_mailbox_id` string
    - `source_file` MailboxFile
      - `id` string, required
      - `mailbox_id` string
      - `basename` string
      - `path` string, required
      - `role` string
      - `created_by_system` string
      - `deleted` boolean
      - `version_reasons` FileVersionReason[]
        - `version_id` string
        - `reason` string
        - `created_by_id` string
        - `version_number` integer
        - `created_at` string, date-time
      - `lock` object
      - `current_file_version` FileVersion
        - `id` string, required
        - `file_id` string, required
        - `name` string
        - `mime_type` string
        - `sha256` string
        - `reason` string, nullable
        - `created_by_system` string
        - `deleted` boolean: True for the version that records a deletion.
        - `ready` boolean
        - `has_text` boolean
        - `version_number` integer, required
        - `byte_size` integer
        - `created_at` string, date-time
        - `created_by` FileActor
          - `id` string
          - `name` string
          - `email` string
        - `updated_by` FileActor
          - `id` string
          - `name` string
          - `email` string
        - `created_by_agent` object
        - `updated_by_agent` object
        - `created_by_api_key` object
        - `updated_by_api_key` object
        - `read` boolean
        - `read_at` string, date-time, nullable
        - `read_by` FileActor
          - `id` string
          - `name` string
          - `email` string
        - `read_by_api_key` FileKey
          - `id` string
          - `label` string
          - `token_type` string
      - `created_by` FileActor
        - `id` string
        - `name` string
        - `email` string
      - `created_at` string, date-time
      - `updated_at` string, date-time
      - `deleted_at` string, date-time
      - `created_by_agent` object
      - `updated_by_agent` object
      - `created_by_api_key` object
      - `updated_by_api_key` object
      - `read` boolean
      - `read_at` string, date-time, nullable
      - `read_by` FileActor
        - `id` string
        - `name` string
        - `email` string
      - `read_by_api_key` FileKey
        - `id` string
        - `label` string
        - `token_type` string
    - `file` MailboxFile
      - `id` string, required
      - `mailbox_id` string
      - `basename` string
      - `path` string, required
      - `role` string
      - `created_by_system` string
      - `deleted` boolean
      - `version_reasons` FileVersionReason[]
        - `version_id` string
        - `reason` string
        - `created_by_id` string
        - `version_number` integer
        - `created_at` string, date-time
      - `lock` object
      - `current_file_version` FileVersion
        - `id` string, required
        - `file_id` string, required
        - `name` string
        - `mime_type` string
        - `sha256` string
        - `reason` string, nullable
        - `created_by_system` string
        - `deleted` boolean: True for the version that records a deletion.
        - `ready` boolean
        - `has_text` boolean
        - `version_number` integer, required
        - `byte_size` integer
        - `created_at` string, date-time
        - `created_by` FileActor
          - `id` string
          - `name` string
          - `email` string
        - `updated_by` FileActor
          - `id` string
          - `name` string
          - `email` string
        - `created_by_agent` object
        - `updated_by_agent` object
        - `created_by_api_key` object
        - `updated_by_api_key` object
        - `read` boolean
        - `read_at` string, date-time, nullable
        - `read_by` FileActor
          - `id` string
          - `name` string
          - `email` string
        - `read_by_api_key` FileKey
          - `id` string
          - `label` string
          - `token_type` string
      - `created_by` FileActor
        - `id` string
        - `name` string
        - `email` string
      - `created_at` string, date-time
      - `updated_at` string, date-time
      - `deleted_at` string, date-time
      - `created_by_agent` object
      - `updated_by_agent` object
      - `created_by_api_key` object
      - `updated_by_api_key` object
      - `read` boolean
      - `read_at` string, date-time, nullable
      - `read_by` FileActor
        - `id` string
        - `name` string
        - `email` string
      - `read_by_api_key` FileKey
        - `id` string
        - `label` string
        - `token_type` string
    - `version` FileVersion
      - `id` string, required
      - `file_id` string, required
      - `name` string
      - `mime_type` string
      - `sha256` string
      - `reason` string, nullable
      - `created_by_system` string
      - `deleted` boolean: True for the version that records a deletion.
      - `ready` boolean
      - `has_text` boolean
      - `version_number` integer, required
      - `byte_size` integer
      - `created_at` string, date-time
      - `created_by` FileActor
        - `id` string
        - `name` string
        - `email` string
      - `updated_by` FileActor
        - `id` string
        - `name` string
        - `email` string
      - `created_by_agent` object
      - `updated_by_agent` object
      - `created_by_api_key` object
      - `updated_by_api_key` object
      - `read` boolean
      - `read_at` string, date-time, nullable
      - `read_by` FileActor
        - `id` string
        - `name` string
        - `email` string
      - `read_by_api_key` FileKey
        - `id` string
        - `label` string
        - `token_type` string

## Other responses

- `default`: Request failed. See error.code. Any 429 or 503 response with Retry-After (for example 503 EMAIL_LABELING_PENDING or 503 EMAIL_INDEX_BUILDING): wait that many seconds, then try the read again. 429 EMAIL_SEND_RATE_LIMITED has no Retry-After. Never retry EMAIL_LOOP_DETECTED.

---

[API](https://skmtc.dev/revdoku/apis/revdoku-api.md) · [All operations](https://skmtc.dev/revdoku/apis/revdoku-api/llms.txt) · [OpenAPI document](https://skmtc.dev/revdoku/apis/revdoku-api/revisions/3ff4e2540a8b?raw)