client.files.startUpload()

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);

{
  "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>"
}

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);

{
  "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>"
}

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:

startUpload(args: {
  projectId: string;
  filename: string;
  declaredSizeBytes: number;
}): Promise<{ file: ProjectFile; uploadUrl: string }>;

Parameters

string

required

Project ID with prefix pp..

string

required

Name of the file being uploaded.

number

required

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

Returns

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

ProjectFile

required

A file stored in a project.

Show Fields

ProjectFileId

required

ID of the project file, with prefix ppf..

ProjectId

required

Project ID with prefix pp..

string

required

Name of the project file.

"pending" | "uploaded" | "failed"

required

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

number

required

Declared maximum size of the file, in bytes.

number | null

required

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

string

required

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

string | null

required

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

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.

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. 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.

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);

{
  "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>"
}

Reference

TypeScript SDK

CLI

HTTP API

Signature

Parameters

Returns

Errors

​Signature

​Parameters

​Returns

​Errors

Signature

Parameters

Returns

Errors