---
title: "Update File"
method: PATCH
path: "/api/v3/file/{file_id}"
tags: ["File"]
---

# Update File

`PATCH /api/v3/file/{file_id}`

## Request

- Base URL: `https://{tenant_name}.benchling.com`
- URL: `https://{tenant_name}.benchling.com/api/v3/file/{file_id}`
- Auth: HTTP bearer

Update File.

## Path parameters

- `file_id` string, required

## Request body

- UpdateFileInput
  - `allowCustomFieldDeletion` boolean: When true, custom fields present on the object but omitted from the update payload will be deleted. When false or omitted, omitting existing custom fields is an error. Defaults to false.
  - `archiveReason` string: Why it is being archived. Required when `archived` is `true`, and not allowed when unarchiving.
  - `archived` boolean: Set to `true` to archive or `false` to unarchive it. Archiving requires `archiveReason`.
  - `customFields` UpdateFileInputCustomFields
  - `expectedVersionId` string: The File's current version as last read by the caller. The update is rejected if another version has been published since.
  - `filename` string: The name of the underlying file. Names the content of `scratchFileId` if given, otherwise renames the current version in place. Must not be blank, and its extension must not be blocked by the tenant's file upload settings.
  - `folderId` string
  - `name` string
  - `scratchFileId` string

## Response `200`

OK

- File: A File represents an uploaded document or data file that is surfaced in Benchling's Data Catalog for discovery and organization. Files are primarily created through Benchling Connect (for external file integrations) and the Analysis Tool (for pipeline outputs). Each File is backed by a ScratchFile containing the actual binary content and upload state. Files are folder-based items that can be starred for quick access, linked to Studies, and support custom fields. Files differ from EntryExternalFile (attachments within notebook entries) and Blob (raw binary storage) in that they are first-class data catalog items with full metadata and discovery capabilities.
  - `__typename` string
  - `archiveReason` string, nullable
  - `archived` boolean
  - `createdAt` string, datetime
  - `creator` PrincipalRef
    - `__typename` string
    - `id` string, api_id
  - `currentVersionId` string, nullable
  - `customFields` CustomField[], nullable
    - `__typename` string
    - `name` string, nullable
    - `value` string, nullable
  - `displayId` string, nullable
  - `externalFileId` string, nullable: Use scratchFile to access externalFileId.
  - `filename` string, nullable: Use scratchFile to access filename.
  - `folder` FolderRef
    - `__typename` string
    - `id` string, api_id
  - `id` string
  - `mimeType` string, nullable: Use scratchFile to access mimeType.
  - `modifiedAt` string, datetime
  - `name` string, nullable
  - `scratchFile` ScratchFileRef
    - `__typename` string
    - `id` string, api_id
  - `versions` string, uri: Published versions of the File, newest first.

## Other responses

- `400`: Bad Request
- `403`: Forbidden
- `404`: Not Found
- `409`: Conflict
- `429`: Too Many Requests
- `500`: Internal Server Error

---

[API](https://skmtc.dev/benchling/apis/benchling-api.md) - [All operations](https://skmtc.dev/benchling/apis/benchling-api/llms.txt) - [OpenAPI document](https://skmtc.dev/benchling/apis/benchling-api/revisions/3873a10bf7b8?raw)