---
title: "Begin a version file upload"
method: POST
path: "/api/repos/{namespace}/{repo_name}/versions/uploads"
tags: ["Version Files"]
---

# Begin a version file upload

`POST /api/repos/{namespace}/{repo_name}/versions/uploads`

## Request

- Base URL: `https://hub.oxen.ai`
- URL: `https://hub.oxen.ai/api/repos/{namespace}/{repo_name}/versions/uploads`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/oxen/apis/oxen-server/docs/api/repos/:namespace/:repo_name/versions/uploads/post.ts> (a function with typed inputs; its response is checked against the schema)

Begin uploading a large file in parts. A file may be at most 1 TiB, a provisional limit. The response's `file` is `awaiting_parts`, with the upload id, the size of every part but the last, the number of parts, and how many parts the upload accepts at once, starting at the first part not yet hashed. When the request gives a destination, a workspace and a path, the file is staged there once its last part arrives. When the store already has the file, `file` is `already_stored`: no parts are needed, and the file is staged at the destination, if one was given. A client whose upload completed without a response, or failed to stage, begins it again.

## Path parameters

- `namespace` string, required
- `repo_name` string, required

## Request body

- BeginVersionUploadRequest: Body of `POST /versions/uploads`: the file's hash and size, and where to stage it once it completes.
  - `destination` WorkspaceDestination: The workspace and path to stage an uploaded file at.
    - `path` string, required
    - `workspace_id` string, required
  - `hash` string, required
  - `size` integer, required

## Response `200`

Upload begun, or the file already stored

- union
  - object: The answer to `POST /versions/uploads`.
    - `oxen_version` string, nullable
    - `status` string, required
    - `status_message` string, required
    - `file` 'awaiting_parts', required
    - `num_parts` integer, required
    - `part_size` integer, required
    - `part_window` integer, required: How many consecutive parts the upload accepts at once, starting at the first part not yet hashed. A part past them gets 429, so a client sending parts in order keeps at most this many in flight.
    - `upload_id` string, required
  - object: The answer to `POST /versions/uploads`.
    - `oxen_version` string, nullable
    - `status` string, required
    - `status_message` string, required
    - `file` 'already_stored', required

## Other responses

- `400`: Invalid hash, size, or destination
- `404`: Repository or workspace not found
- `429`: Repository busy with maintenance

---

[API](https://skmtc.dev/oxen/apis/oxen-server.md) - [All operations](https://skmtc.dev/oxen/apis/oxen-server/llms.txt) - [OpenAPI document](https://skmtc.dev/oxen/apis/oxen-server/revisions/2ae578129949?raw)