---
title: "Start an upload"
method: POST
path: "/api/v1/files/uploads"
tags: ["Files"]
---

# Start an upload

`POST /api/v1/files/uploads`

## Request

- Base URL: `https://app.easyscraper.com`
- URL: `https://app.easyscraper.com/api/v1/files/uploads`
- Auth: API key in cookie `better-auth.session_token`

Checks that a file may be uploaded for `purpose` (its type and size, the user's permissions and the organization's `storage` limit) and returns a signed request that uploads it straight to storage, which works for 10 minutes. Send the file with that request's method and headers, then put it to use with the purpose's endpoint (`PUT /v1/users/me/image` for `avatar`, `PUT /v1/organizations/{organizationId}/logo` for `logo`, `attachmentIds` of `POST /v1/feedback` and `PATCH /v1/feedback/{number}` for `feedback-attachment`). Files that are never put to use are deleted after a day

## Request body

- object
  - `purpose` 'avatar' | 'logo' | 'feedback-attachment', required
  - `organizationId` string, uuid
  - `contentType` string, required
  - `size` integer, required

## Response `200`

OK

- object
  - `fileId` string, uuid, required
  - `upload` object, required
    - `url` string, uri, required
    - `method` 'PUT', required
    - `headers` object, required

## Other responses

- `400`: 400
- `401`: 401
- `403`: 403
- `404`: 404
- `413`: 413
- `429`: 429
- `503`: 503

## Changes

- **2026-11-02** `a12cef98c52b`: 1 breaking
  - added `subschema #1` to the response body `oneOf` list for the response status `400`
- **2026-10-31** `3e642e95991a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/easyscraper/apis/easy-scraper-api/changes/api/v1/files/uploads/post.md)

---

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