---
title: "Upload a complete task file"
method: POST
path: "/api/tasks/{id}/files/upload"
---

# Upload a complete task file

`POST /api/tasks/{id}/files/upload`

## Request

- Base URL: `https://www.toma.com`
- URL: `https://www.toma.com/api/tasks/{id}/files/upload`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `better-auth.session_token`

Reserve the file and return one short-lived upload request. Supply original size and SHA-256 hex. Send the whole original file: POST multipart/form-data with exact returned fields and file last, or PUT raw bytes. Then call the file complete endpoint. No client splitting or base64. Ready bytes are immutable. Upload capabilities are private and expire; S3 capabilities can only write a bounded incoming object and never a ready file. Programs, installers, disk images, shortcuts, and macro-enabled Office files are refused by name. Windows, macOS, and Linux programs, Office macros, password-protected zip files, zip files that contain programs, and PDFs with visible script or launch actions are also refused by content; completing such an upload removes it.

## Path parameters

- `id` string, required

## Request body

- object
  - `path` string, required
  - `size` integer, required
  - `sha256` string, required
  - `folder` 'poster' | 'worker', required

## Response `201`

Whole-file upload request. Keep credentials private.

- object
  - `file` TaskFile, required
    - `id` string, required
    - `folder` 'poster' | 'worker', required
    - `public` boolean, required: A poster file anyone can download from the open task's page (publicFiles on the task).
    - `path` string, required
    - `caution` string, nullable, required: A warning to show the user before they download or open this kind of file (archives, scripts, older Office files, web pages); null when there is none.
    - `hireId` string, nullable, required
    - `size` integer, required
    - `received` integer, required
    - `status` 'uploading' | 'ready' | 'deleting', required
    - `createdAt` string, date-time, required
    - `canWrite` boolean, required
  - `upload` object, required
    - `url` string, uri, required
    - `method` 'POST' | 'PUT', required
    - `fields` object
    - `headers` object
  - `expiresAt` string, date-time, required

## Other responses

- `400`: Invalid file metadata.
- `401`: Sign in first.
- `403`: File access denied.
- `404`: No accessible file area.
- `409`: Path or quota conflict.
- `413`: The request body exceeds 524288 bytes.
- `503`: Storage unavailable.

---

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