---
title: "Create a file"
method: POST
path: "/files"
tags: ["files"]
---

# Create a file

`POST /files`

## Request

- Base URL: `https://{tenant_name}.benchling.com/api/v2`
- URL: `https://{tenant_name}.benchling.com/api/v2/files`
- Auth: HTTP bearer

Create a file of a supported type. Currently, we support these file extensions: .csv; .html;
.jmp, .jrn, .jrp (JMP); .jpeg, .jpg (JPEG); .png; .pdf; .zip; and .txt.

A successful file upload requires 3 calls in serial:
1. [Create a file](https://docs.benchling.com/docs/api/v2/benchling-api/files/create-file), this endpoint, which returns an S3 `PUT` URL for the 2nd
   call and a file ID for the 3rd call
2. Upload the file contents to S3. Add `x-amz-server-side-encryption: AES256` to the request headers,
   because we use server-side encryption. Here is a `curl` example:
   ```bash
   curl -H "x-amz-server-side-encryption: AES256" -X PUT -T <LOCAL_FILE> -L <S3_PUT_URL>
   ```
3. [Update the file](https://docs.benchling.com/docs/api/v2/benchling-api/files/patch-file), which marks the upload as `SUCCEEDED`

Note: URL is valid for 1 hour after being returned from this endpoint. It should not be stored
persistently for later use.

Files up to 30MB are supported.

## Request body

- FileCreate
  - `customFields` CustomFields
  - `filename` string: Filename for the file
  - `folderId` string: ID of the folder that contains the file
  - `name` string: Display name for the file

## Response `200`

OK

- File
  - `errorMessage` string, nullable
  - `uploadStatus` 'IN_PROGRESS' | 'SUCCEEDED' | 'FAILED_VALIDATION' | 'NOT_UPLOADED'
  - `archiveRecord` ArchiveRecord
    - `reason` string
  - `createdAt` string, date-time: Date and time the file was created
  - `creator` FileCreator: UserSummary of the user who created the file
    - `handle` string
    - `id` string
    - `name` string
  - `customFields` CustomFields
  - `displayId` string: User-friendly ID of the file
  - `filename` string
  - `folderId` string: ID of the folder that contains the file
  - `id` string
  - `modifiedAt` string, date-time: Date and time the file was last modified
  - `name` string

## Other responses

- `400`: Bad Request
- `403`: Forbidden

---

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