> For the complete documentation index, see [llms.txt](https://docs.nebulablock.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nebulablock.com/api-reference/platform-api/list-workspaces/upload-file.md).

# Upload File

Upload a file into a bucket through the Platform API using multipart form data.

Upload a file into a bucket. This endpoint takes `multipart/form-data`, not JSON.

## HTTP Request

`POST` `{API_URL}/object-storage/upload`

where `API_URL = https://api.nebulablock.com/api/v1`.

## Form Parameters

| Parameter             | Requirement | Type      | Description                                                                               |
| --------------------- | ----------- | --------- | ----------------------------------------------------------------------------------------- |
| `object_storage_name` | Required    | `string`  | The workspace holding the bucket                                                          |
| `bucket_name`         | Required    | `string`  | The destination bucket                                                                    |
| `file`                | Required    | `file`    | The file to upload                                                                        |
| `path`                | Required    | `string`  | The key prefix to store the file under. Pass an empty string to upload to the bucket root |
| `team_id`             | Optional    | `integer` | Act on a team's storage. See [Teams](/account/teams.md)                                   |

The final object key is `path` joined to the uploaded file's own filename — uploading `model.safetensors` with `path=run-42` stores it as `run-42/model.safetensors`. Backslashes are normalised to `/`, and a `path` containing `..` is rejected as path traversal.

## Response Attributes

#### data `string`

The resulting object key. On failure the shape differs by cause: a rejected `path` (traversal) returns `null`, while a failed upload returns an empty list.

#### status `string`

`success` or `failed`.

#### message `string`

A description of the result.

> **Note:** Business failures on this endpoint are returned as **HTTP 200 with `"status": "failed"`** and an explanatory `message`. Check `status`, not just the HTTP status code.

> **Note:** This endpoint buffers the whole file through the platform API. For large files and bulk transfers, go straight to the S3 endpoint with `s3cmd` or an AWS SDK — see [s3cmd on Linux and macOS](/products/object-storage/s3cmd-linux-macos.md) and [Python SDK](/products/object-storage/sdk-python.md).

## Example

#### Request

```bash
curl -X POST '{API_URL}/object-storage/upload' \
-H 'Authorization: Bearer {TOKEN}' \
-F 'object_storage_name=research-datasets' \
-F 'bucket_name=checkpoints' \
-F 'path=run-42' \
-F 'file=@./model.safetensors'
```

#### Response

```json
{
    "data": "run-42/model.safetensors",
    "message": "File uploaded successfully",
    "status": "success"
}
```

## See also

* [List Files](/api-reference/platform-api/list-workspaces/list-files.md)
* [Get Download URL](/api-reference/platform-api/list-workspaces/get-download-url.md)
* [Delete File](/api-reference/platform-api/list-workspaces/delete-file.md)