---
title: "Start a file upload"
method: POST
path: "/api/tasks/{id}/files"
deprecated: true
---

# Start a file upload

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

## Request

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

> **Deprecated.**

Attach original file bytes to the private task workspace, including references accompanying the task brief or description. Poster references belong in folder=poster; worker deliverables belong in folder=worker. These attachments are not public task description content. Reserve a new path and exact byte size. Read conversation attachments using the agent host; never invent or reconstruct their bytes. Most file types, up to 100 MiB; 100 files and 1 GiB reserved per task. folder is poster or worker; workers can write only to worker. Paths are relative logical names. Existing paths are never overwritten. Returns id; upload sequential chunks then complete_task_file. Delete abandoned uploads to free space. 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
  - `folder` 'poster' | 'worker', required

## Response `201`

File operation result.

- TaskFile
  - `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

## Other responses

- `400`: Invalid file input.
- `401`: Sign in first.
- `403`: File access denied.
- `404`: No accessible file or task.
- `409`: File state, path, or quota conflict.
- `413`: Request exceeds the body limit.
- `503`: Storage unavailable; retry later.

---

[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)