---
title: "Rename a file"
method: PATCH
path: "/files/{file_id}"
tags: ["files"]
---

# Rename a file

`PATCH /files/{file_id}`

Updates the file's display name. Metadata only: storage is keyed by id, so the object never moves and existing URLs keep working, and past deliveries keep the name they were sent under. Only an uploaded file can be renamed; a captured file's name is part of its provenance, so renaming one is rejected.

## Path parameters

- `file_id` string, uuid, required — file identifier to rename

## Request body

- FileRenameRequest — Updates an upload's display name.
  - `$schema` string, uri — A URL to the JSON Schema for this object.
  - `filename` string, required — New display name for the file.

## Response `200`

OK

- RenameFileOutputBody
  - `$schema` string, uri — A URL to the JSON Schema for this object.
  - `file` FileSummary, required — One file in the org's library.
    - `attachment_url` string — Short-lived signed URL that downloads the file as an attachment under its name. Present only for ready files.
    - `bytes_transferred` integer — Bytes moved so far for an in-flight phone transfer. Absent until the phone reports progress.
    - `capture_error` string — Reason the capture failed, when it did. Present only for captures.
    - `capture_state` 'detected' | 'uploading' | 'ready' | 'skipped_size' | 'skipped_quota' | 'skipped_type' | 'dropped_teardown' | 'failed' — Capture lifecycle: detected/uploading while in flight, ready when usable, or a terminal skip/failure with its reason. Present only for captures.
    - `checksum` string — SHA-256 of the bytes, computed on the phone during a capture upload. Present only for captures.
    - `created_at` string, date-time, required — When the file was registered: upload registration, or capture detection.
    - `download_url` string — Short-lived signed URL to read the file's bytes. Present only for ready files; re-list to refresh an expired one.
    - `duration_seconds` integer — Video duration in seconds.
    - `filename` string, required — Original filename; used as the display name when the file lands on a phone.
    - `height` integer — Intrinsic pixel height of the source.
    - `id` string, required — File identifier. Unique across the whole library; deliverable to a phone regardless of source.
    - `mime_type` string, required — Declared MIME type, pinned by the presigned upload.
    - `on_phone_count` integer, required — Distinct phones currently holding or receiving a copy. Deleting the file recalls these.
    - `preview_state` 'processing' | 'ready' | 'unavailable', required — Whether the preview exists, is still being generated, or will never be available for this format.
    - `reel_url` string — Short-lived signed URL for the animated hover preview. Videos only; absent until generated.
    - `session_id` string — Session that produced the file. Present only for captures.
    - `size_bytes` integer, required — Declared size in bytes, pinned by the presigned upload.
    - `source` 'upload' | 'capture', required — How the file entered the library: upload (put in directly) or capture (lifted off a session).
    - `status` 'uploading' | 'ready', required — uploading until the object is verified in storage, then ready. For a capture, read capture_state for the fuller lifecycle.
    - `surface` 'phone' — Which surface a capture came off (phone today). Absent for a direct upload.
    - `thumbnail_url` string — Short-lived signed URL for the generated preview image. Absent while generation is pending, and permanently absent for formats without a preview.
    - `width` integer — Intrinsic pixel width of the source.

## Other responses

- `default` — Error

---

[API](https://skmtc.dev/axilioai/apis/axilio-api.md) · [All operations](https://skmtc.dev/axilioai/apis/axilio-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/axilioai/axilio-api/revisions/8a66f81813b3/schema)