---
title: "Upload a file to project storage"
method: POST
path: "/api/storage/{project_id}/upload"
tags: ["Storage"]
---

# Upload a file to project storage

`POST /api/storage/{project_id}/upload`

## Request

- Base URL: `https://core.blink.new`
- URL: `https://core.blink.new/api/storage/{project_id}/upload`
- Auth: HTTP bearer

Upload a file to the project's cloud storage bucket. The server generates a
UUID-based filename to prevent path traversal attacks — client-supplied names
are never used directly. An optional `path` body field provides a folder hint
for organizing uploads (e.g. `images/avatars`).

**Security**: Dangerous file types (executables, scripts, HTML, etc.) are
blocked. Projects may require a Bearer JWT token when the storage security
policy has `require_auth` enabled. A signed-in uploader is recorded on the
file, which is what lets that same user delete it later with `remove`.

## Path parameters

- `project_id` string, required

## Request body `multipart/form-data`

- object
  - `file` string, binary, required: The file to upload
  - `path` string: Optional folder hint for organizing the file (sanitized server-side)

## Response `200`

File uploaded successfully

- StorageResponse
  - `data` union
    - FileObject
      - `id` string, uuid
      - `name` string
      - `bucket_id` string
      - `owner` string, nullable
      - `owner_id` string, nullable
      - `version` string, nullable
      - `created_at` string, date-time
      - `updated_at` string, date-time
      - `last_accessed_at` string, date-time
      - `metadata` object
        - `size` integer
        - `mimetype` string
        - `cacheControl` string
      - `user_metadata` object
    - FileObject[]
      - `id` string, uuid
      - `name` string
      - `bucket_id` string
      - `owner` string, nullable
      - `owner_id` string, nullable
      - `version` string, nullable
      - `created_at` string, date-time
      - `updated_at` string, date-time
      - `last_accessed_at` string, date-time
      - `metadata` object
        - `size` integer
        - `mimetype` string
        - `cacheControl` string
      - `user_metadata` object
    - object
  - `error` object, nullable
    - `message` string
    - `statusCode` string

## Other responses

- `400`: Missing file, blocked file type, or invalid project ID
- `401`: Authentication required or invalid API key
- `409`: File collision at generated path (UUID collision — extremely rare)
- `500`: Internal storage error

---

[API](https://skmtc.dev/blink/apis/blink-apis.md) - [All operations](https://skmtc.dev/blink/apis/blink-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/blink/apis/blink-apis/revisions/4c59c706078e?raw)