client.files.finalizeUpload()

import { createClient } from "@toloka-platform/sdk";

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

const file = await client.files.finalizeUpload({
  projectId: "pp.019a0000-0000-7000-8000-000000000001",
  fileId: "ppf.019a0000-0000-7000-8000-000000000001"
});
console.log(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>"
}

import { createClient } from "@toloka-platform/sdk";

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

const file = await client.files.finalizeUpload({
  projectId: "pp.019a0000-0000-7000-8000-000000000001",
  fileId: "ppf.019a0000-0000-7000-8000-000000000001"
});
console.log(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>"
}

After uploading bytes to uploadUrl, call this endpoint to verify the file. Returns updated file metadata. A missing file or size above 100 MiB returns 400; a failed upload or a file that changes during verification returns 409.

Signature

Method signature on client.files:

finalizeUpload(args: {
  projectId: string;
  fileId: string;
}): Promise<ProjectFile>;

Parameters

string

required

Project ID with prefix pp..

string

required

ID of the project file, with prefix ppf..

Returns

Promise<ProjectFile> A file stored in a project.

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.

Errors

HTTP errors throw PotatoApiError. The endpoint documents these error responses:

Status	Description
400	Uploaded file is missing or too large
404	Project or file not found
429	Rate limit exceeded

HTTP endpoint: POST /projects/{projectId}/files/{fileId}/finalize.

import { createClient } from "@toloka-platform/sdk";

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

const file = await client.files.finalizeUpload({
  projectId: "pp.019a0000-0000-7000-8000-000000000001",
  fileId: "ppf.019a0000-0000-7000-8000-000000000001"
});
console.log(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>"
}

Reference

TypeScript SDK

CLI

HTTP API

client.files.finalizeUpload()

Signature

Parameters

Returns

Errors

​Signature

​Parameters

​Returns

​Errors

Signature

Parameters

Returns

Errors