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

# Complete Upload

> Finalize a direct-to-cloud upload after all parts have been uploaded

## Overview

Finalize a direct-to-cloud upload after the client has `PUT` every part to its presigned URL. The server validates the supplied `part_token`s, assembles the final file, and registers it with the organization.

Parts already submitted via [Checkpoint Upload Parts](./checkpoint-parts) do not need to be repeated here — only supply tokens for parts not yet checkpointed.

<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 that have not already been checkpointed. Pass an empty array when every part of the upload has been [checkpointed](./checkpoint-parts).

  <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, including its surrounding quotes
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="integrity_checksum" type="string">
  Optional whole-file checksum, base64-encoded. When provided, the server queries the storage backend for the checksum it computed over the full object and compares; a mismatch marks the file as corrupt and returns an error. Omit to skip verification entirely.

  The encoding and byte length must match the algorithm returned by [Initiate Upload](./initiate-upload) (e.g. `crc32c` → 4 raw bytes → 8 base64 characters with `=` padding). Sending a checksum when `integrity_algorithm: none` is returned is an error.
</ParamField>

## Response

<ResponseField name="file_uid" type="string">
  Internal unique identifier of the completed file
</ResponseField>

<ResponseField name="file_name" type="string">
  Name of the completed file
</ResponseField>

<ResponseField name="num_bytes" type="integer">
  Total size of the completed file in bytes
</ResponseField>

<ResponseField name="file_status" type="string">
  Lifecycle status of the file. After a successful upload, the status is `Registered`. Other values are: `Unknown`, `Uploading`, `Ingested`, `Deleting`, `Deleted`, and `Corrupt`.

  <Note>
    The format of the status string returned for direct-to-cloud uploads is different from the `file_status` string returned by the [Get File Metadata](/api-reference/files/get-metadata) endpoint.
  </Note>
</ResponseField>

<ResponseField name="file_attributes" type="object">
  Type-specific attributes for the file. Shape depends on the file type — see [Get File Metadata](./get-metadata) for the variants.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X POST https://api.u1.archetypeai.app/v0.5/files/uploads/upl_1mehceg8cn80qsekh46143whrx/complete \
    -H "Authorization: Bearer $ATAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "parts": [
        { "part_number": 4, "part_token": "\"f912ab83e0d1...\"" },
        { "part_number": 5, "part_token": "\"203fa182b97c...\"" }
      ]
    }'
  ```

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

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

  # Only include parts that were NOT previously checkpointed
  remaining_parts = [
      {"part_number": 4, "part_token": '"f912ab83e0d1..."'},
      {"part_number": 5, "part_token": '"203fa182b97c..."'},
  ]

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

  result = response.json()
  print(f"file_uid: {result['file_uid']}  status: {result['file_status']}")
  ```

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

  const remainingParts = [
    { part_number: 4, part_token: '"f912ab83e0d1..."' },
    { part_number: 5, part_token: '"203fa182b97c..."' },
  ];

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

  const result = await response.json();
  console.log(`file_uid: ${result.file_uid}  status: ${result.file_status}`);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Success theme={"system"}
  {
    "file_uid": "fil_5hx819ysp38n2rt1f5fv0wsxgh",
    "file_name": "training-data.parquet",
    "num_bytes": 1073741824,
    "file_status": "Registered",
    "file_attributes": {
      "metadata_status": "not_extracted"
    }
  }
  ```

  ```json 400 - Validation error theme={"system"}
  {
    "errors": [
      {
        "code": "size_mismatch",
        "message": "Combined size of submitted parts does not match the upload's declared num_bytes.",
        "suggestion": "Verify each part_token corresponds to the matching part_number and that all parts were uploaded.",
        "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 aborted.",
        "error_uid": "err-xxxxxxxx"
      }
    ]
  }
  ```

  ```json 409 - Upload already completed theme={"system"}
  {
    "errors": [
      {
        "code": "upload_already_completed",
        "message": "Upload has already been completed.",
        "suggestion": "Use the file_id from the original completion response to operate on the file.",
        "error_uid": "err-xxxxxxxx"
      }
    ]
  }
  ```
</ResponseExample>