---
title: "Create a file"
method: POST
path: "/documents/v1"
tags: ["Documents"]
---

# Create a file

`POST /documents/v1`

## Request

- Base URL: `https://api.mitti.com`
- URL: `https://api.mitti.com/documents/v1`
- Auth: HTTP bearer

Create a new file in Documents and return a URL to upload the file content to.

## Request body

- S12DocumentsV1CreateFileRequest
  - `path` string[]: An array of folder names that defines the path where the file will be stored. The `path` is relative to the `parent_id` if it is provided. If not, it starts from the root folder. The API will automatically create any folders in the path that don’t exist. Each folder name must be 1-255 characters and exclude invalid characters.
  - `name` string: The name of the file. Must be between 1-255 characters and exclude invalid characters.
  - `file_type` 'MEDIA_TYPE_IMAGE' | 'MEDIA_TYPE_VIDEO' | 'MEDIA_TYPE_PDF' | 'MEDIA_TYPE_DOCX' | 'MEDIA_TYPE_XLSX' | 'MEDIA_TYPE_PPTX' | 'MEDIA_TYPE_CSV': - MEDIA_TYPE_IMAGE: An image file (GIF, JPG, PNG, WEBP). - MEDIA_TYPE_VIDEO: A video file (MP4, MOV). - MEDIA_TYPE_PDF: A PDF document. - MEDIA_TYPE_DOCX: A Microsoft Word document (DOCX, DOC). - MEDIA_TYPE_XLSX: A Microsoft Excel spreadsheet (XLSX, XLS). - MEDIA_TYPE_PPTX: A Microsoft PowerPoint presentation (PPTX, PPT). - MEDIA_TYPE_CSV: A CSV file.
  - `file_size` integer: The size of the file in bytes. Must not exceed 50MB. This field is required if `file_type` is provided.
  - `parent_id` string: The ID of the folder where the file should be stored. Any folders defined in the `path` will be created inside the parent folder. If you don’t provide a parent_id, the file will be stored in the root folder. To get the `parent_id`, open the folder in the SafetyCulture web app and copy the last part of the URL. For example, in this link `https://app.safetyculture.com/documents/9dd76834-65ef-41d3-815c-964df32450e4`, the parent ID is `9dd76834-65ef-41d3-815c-964df32450e4`.
  - `file_extension` string: The file extension of the uploaded blob (e.g. "pdf", "jpg"), without the leading dot. Used to populate the file's extension when the extension cannot be derived from `name` or the underlying media metadata is unavailable.

## Response `200`

A successful response.

- S12DocumentsV1CreateFileResponse
  - `file_id` string: The ID of the file that was created.
  - `upload_url` string: The URL where you must upload the file’s binary content. It is valid for 20 minutes.
  - `path` string: If provided, the full folder path where the file was stored.
  - `name` string: The name of the created file.

## Other responses

- `default`: An unexpected error response.

## Changes

- **2026-11-03** `eb6bb843bf18`: 1 info
  - added the new optional request property `file_extension`

[Operation history](https://skmtc.dev/safetyculture/apis/safetyculture-api/changes/documents/v1/post.md)

---

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