---
title: "Upload File"
method: POST
path: "/api/v1/uploads"
tags: ["Uploads"]
---

# Upload File

`POST /api/v1/uploads`

Upload a file to Todoist.

This endpoint accepts file uploads via two methods:

1. **Multipart form-data** (recommended):
   - Send the file as a form field with the actual file content
   - Optionally include `project_id` as another form field
   - The filename will be extracted from the Content-Disposition header

2. **Raw binary stream**:
   - Send the file content directly in the request body
   - Set `Content-Type` header to the file's MIME type
   - Set `X-File-Name` header with the desired filename
   - Optionally include `project_id` as a query parameter

The optional `project_id` parameter can be used to apply workspace-specific
upload limits when uploading to a workspace project.

## Response `200`

Successful Response

- UploadResult
  - `file_url` string, required — URL of the uploaded file.
  - `file_name` string, required — Name of the uploaded file.
  - `file_size` integer, required — Size of the uploaded file in bytes.
  - `file_type` string, required — MIME type of the uploaded file.
  - `resource_type` string, required — Detected resource type of the upload.
  - `image` string, nullable — Image URL for image uploads, or `null` for non-image files.
  - `image_width` integer, nullable — Image width in pixels, or `null` for non-image files.
  - `image_height` integer, nullable — Image height in pixels, or `null` for non-image files.
  - `upload_state` 'pending' | 'completed' — Upload processing state.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found

---

[API](https://skmtc.net/todoist/apis/todoist-api.md) · [All operations](https://skmtc.net/todoist/apis/todoist-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/todoist/todoist-api/revisions/69a962f1578f/schema)