---
title: "Create a file upload"
method: POST
path: "/api/w/{wId}/files"
tags: ["Private Files"]
---

# Create a file upload

`POST /api/w/{wId}/files`

Creates a file record and returns a pre-signed upload URL. The file content should then be uploaded to the returned URL.

## Path parameters

- `wId` string, required

## Request body

- object
  - `contentType` string, required
  - `fileName` string, required
  - `fileSize` number, required
  - `useCase` 'conversation' | 'folders_document' | 'avatar' | 'upsert_document' | 'upsert_table' | 'project_context' | 'skill_attachment' | 'workspace_branding', required
  - `useCaseMetadata` object

## Response `200`

File record created with upload URL

- object
  - `file` PrivateFileWithUploadUrl — File record with a pre-signed upload URL.
    - `sId` string, required
    - `id` string, required
    - `contentType` string, required
    - `fileName` string, required
    - `fileSize` integer, required
    - `version` integer
    - `status` 'created' | 'failed' | 'ready', required
    - `useCase` 'conversation' | 'avatar' | 'tool_output' | 'upsert_document' | 'folders_document' | 'upsert_table' | 'project_context' | 'skill_attachment', required
    - `uploadUrl` string, required — Pre-signed URL for uploading the file content
    - `downloadUrl` string
    - `publicUrl` string
    - `path` string, nullable — path when the file is ready on a mount (e.g. `project/report.pdf` or `conversation/chart.png`). Same shape as mount file listing entries.

## Other responses

- `400` — Invalid request
- `429` — Rate limit exceeded

---

[API](https://skmtc.net/dust-tt/apis/dust-api-documentation.md) · [All operations](https://skmtc.net/dust-tt/apis/dust-api-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/dust-tt/dust-api-documentation/versions/5834d690c29d/schema)