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

> ## Agent Instructions
> Start with /introduction/getting-started. Use the Direct Query API (POST /query) with the Newton Fusion model (text, image, and video reasoning) or the Newton Omega encoder (time-series embeddings). ATAI_API_ENDPOINT must include the version path: /v0.5 for most APIs, /v0.6 for the Fine-Tuning Service. Pages whose descriptions are marked (Archived) document the legacy Lens runtime — do not use them for new projects.

# Checkpoint Upload Parts

> Persist part_tokens for completed parts so they can be skipped on resume

## Overview

Checkpoint a subset of an upload's completed parts. The server stores each `part_token` (the `ETag` returned from a successful part `PUT`) so that:

* A later [Initiate Upload](./initiate-upload) call with `resume_if_started=true` skips the checkpointed parts and only returns presigned URLs for the remaining ones.
* Checkpointed parts do not need to be re-supplied on the [Complete Upload](./complete-upload) call.

Use this endpoint to make incremental progress durable when uploading a large file in many parts.

<Note>
  Direct-to-cloud file uploads support files up to 250GB.
</Note>

## Path Parameters

<ParamField path="upload_id" type="string" required>
  Upload identifier returned by [Initiate Upload](./initiate-upload)
</ParamField>

## Request Body

<ParamField body="parts" type="array" required>
  Completed parts to checkpoint

  <Expandable title="part properties">
    <ParamField body="part_number" type="integer" required>
      1-based part index (matches the `part_number` returned by [Initiate Upload](./initiate-upload))
    </ParamField>

    <ParamField body="part_token" type="string" required>
      The `ETag` value returned by the part's `PUT` request
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="num_checkpointed" type="integer">
  Number of parts that were newly checkpointed (equal to the number of parts in the request after validation)
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X POST https://api.u1.archetypeai.app/v0.5/files/uploads/upl_1mehceg8cn80qsekh46143whrx/parts/checkpoint \
    -H "Authorization: Bearer $ATAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "parts": [
        { "part_number": 1, "part_token": "\"e1b3a4cd87f3...\"" },
        { "part_number": 2, "part_token": "\"a2c8f7b9e081...\"" },
        { "part_number": 3, "part_token": "\"d40fa2c81b9e...\"" }
      ]
    }'
  ```

  ```python Python theme={"system"}
  import requests
  import os

  api_key = os.environ.get("ATAI_API_KEY")
  upload_id = "upl_1mehceg8cn80qsekh46143whrx"

  # part_tokens are the ETag header values returned from each PUT to the
  # presigned URL; collect them as you upload parts.
  parts = [
      {"part_number": 1, "part_token": '"e1b3a4cd87f3..."'},
      {"part_number": 2, "part_token": '"a2c8f7b9e081..."'},
      {"part_number": 3, "part_token": '"d40fa2c81b9e..."'},
  ]

  response = requests.post(
      f"https://api.u1.archetypeai.app/v0.5/files/uploads/{upload_id}/parts/checkpoint",
      headers={
          "Authorization": f"Bearer {api_key}",
          "Content-Type": "application/json",
      },
      json={"parts": parts},
  )

  print(response.json())
  ```

  ```javascript JavaScript theme={"system"}
  const uploadId = "upl_1mehceg8cn80qsekh46143whrx";

  const parts = [
    { part_number: 1, part_token: '"e1b3a4cd87f3..."' },
    { part_number: 2, part_token: '"a2c8f7b9e081..."' },
    { part_number: 3, part_token: '"d40fa2c81b9e..."' },
  ];

  const response = await fetch(
    `https://api.u1.archetypeai.app/v0.5/files/uploads/${uploadId}/parts/checkpoint`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.ATAI_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ parts }),
    }
  );

  console.log(await response.json());
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Success theme={"system"}
  {
    "num_checkpointed": 3
  }
  ```

  ```json 400 - Invalid request theme={"system"}
  {
    "errors": [
      {
        "code": "invalid_upload_parts",
        "message": "Parts list is empty or contains duplicate or out-of-range part numbers.",
        "suggestion": "Send a non-empty list of unique part numbers within [1, num_parts].",
        "error_uid": "err-xxxxxxxx"
      }
    ]
  }
  ```

  ```json 401 - Unauthorized theme={"system"}
  {
    "errors": [
      {
        "code": "unauthorized_request",
        "message": "Unauthorized or invalid access.",
        "suggestion": "Provide valid authentication credentials and ensure they have the required permissions.",
        "error_uid": "err-xxxxxxxx"
      }
    ]
  }
  ```

  ```json 404 - Upload not found theme={"system"}
  {
    "errors": [
      {
        "code": "upload_not_found",
        "message": "No upload with the given upload_id was found for the organization.",
        "suggestion": "Verify the upload_id and that the upload has not been completed or aborted.",
        "error_uid": "err-xxxxxxxx"
      }
    ]
  }
  ```

  ```json 409 - Upload already completed theme={"system"}
  {
    "errors": [
      {
        "code": "upload_already_completed",
        "message": "Upload has already been completed; checkpoint is not allowed.",
        "suggestion": "Begin a new upload via /uploads/initiate.",
        "error_uid": "err-xxxxxxxx"
      }
    ]
  }
  ```
</ResponseExample>