> ## Documentation Index
> Fetch the complete documentation index at: https://docs.platform.toloka.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# client.files.startUpload()

> Start a project file upload.

Send `filename` and `declaredSizeBytes`, up to 100 MiB. Returns file metadata and `uploadUrl`. PUT the file bytes to that URL with the required `x-ms-blob-type: BlockBlob` header. After the PUT succeeds, finalize the upload.

## Signature

Method signature on `client.files`:

```ts theme={null}
startUpload(args: {
  projectId: string;
  filename: string;
  declaredSizeBytes: number;
}): Promise<{ file: ProjectFile; uploadUrl: string }>;
```

## Parameters

**projectId** `string` *required*

Project ID with prefix `pp.`.

**filename** `string` *required*

Name of the file being uploaded.

**declaredSizeBytes** `number` *required*

Declared maximum file size in bytes, up to 100 MiB.

## Returns

`Promise<{ file: ProjectFile; uploadUrl: string }>`

**file** `ProjectFile` *required*

A file stored in a project.

**Fields**

**id** `ProjectFileId` *required*

ID of the project file, with prefix `ppf.`.

**projectId** `ProjectId` *required*

Project ID with prefix `pp.`.

**filename** `string` *required*

Name of the project file.

**status** `"pending" | "uploaded" | "failed"` *required*

File state: `pending` before finalization, `uploaded` after successful finalization, or `failed` if the upload failed.

**declaredSizeBytes** `number` *required*

Declared maximum size of the file, in bytes.

**uploadedSizeBytes** `number | null` *required*

Finalized file size in bytes, or null before successful finalization.

**createdAt** `string` *required*

Time the file upload was started, as an ISO 8601 timestamp.

**uploadedAt** `string | null` *required*

Time the upload was finalized, as an ISO 8601 timestamp, or null before successful finalization.

**url** `string` *required*

The file download endpoint. API keys and signed-in users receive a 302 redirect to the download link. Project-scoped tokens receive JSON with a `url` field.

**uploadUrl** `string` *required*

Signed URL for uploading file bytes with a PUT request and the `x-ms-blob-type: BlockBlob` header.

## Errors

HTTP errors throw [`PotatoApiError`](https://docs.platform.toloka.ai/docs/sdk/errors). The endpoint documents these error responses:

| Status | Description |
| - | - |
| 400 | File size is invalid |
| 404 | Project not found |
| 429 | Rate limit exceeded |

HTTP endpoint: [`POST /projects/{projectId}/files`](https://docs.platform.toloka.ai/docs/api-reference/files/create-project-file-upload).

```ts startUpload() theme={null}
import { createClient } from "@toloka-platform/sdk";

const client = createClient({
  baseUrl: "https://platform.toloka.ai",
  apiKey: process.env.TOLOKA_API_KEY!,
});

const data = "Answer using the supplied context.";

const upload = await client.files.startUpload({
  projectId: "pp.019a0000-0000-7000-8000-000000000001",
  filename: "prompt.txt",
  declaredSizeBytes: new TextEncoder().encode(data).byteLength
});
console.log(upload);
```

```json startUpload() theme={null}
{
  "file": {
    "id": "ppf.019a0000-0000-7000-8000-000000000001",
    "projectId": "pp.019a0000-0000-7000-8000-000000000001",
    "filename": "<string>",
    "status": "pending",
    "declaredSizeBytes": 0,
    "uploadedSizeBytes": null,
    "createdAt": "2026-01-01T00:00:00Z",
    "uploadedAt": null,
    "url": "<string>"
  },
  "uploadUrl": "<string>"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.