Skip to main content
POST
/
files
/
uploads
/
initiate
curl -X POST https://api.u1.archetypeai.app/v0.5/files/uploads/initiate \
  -H "Authorization: Bearer $ATAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "training-data.parquet",
    "file_type": "application/x-parquet",
    "num_bytes": 1073741824,
    "resume_if_started": false
  }'

{
  "upload_id": "upl_1mehceg8cn80qsekh46143whrx",
  "file_uid": "fil_5hx819ysp38n2rt1f5fv0wsxgh",
  "file_name": "training-data.parquet",
  "total_bytes": 1073741824,
  "num_parts": 128,
  "part_size": 8388608,
  "integrity_algorithm": "crc32c",
  "is_resume": false,
  "parts": [
    {
      "part_number": 1,
      "url": "https://storage.example.com/upload/upl_1mehceg8cn80qsekh46143whrx/1?X-Amz-Signature=...",
      "offset": 0,
      "length": 8388608,
      "expires_at": "2026-04-28T15:32:18Z"
    },
    {
      "part_number": 2,
      "url": "https://storage.example.com/upload/upl_1mehceg8cn80qsekh46143whrx/2?X-Amz-Signature=...",
      "offset": 8388608,
      "length": 8388608,
      "expires_at": "2026-04-28T15:32:18Z"
    }
  ]
}

​
Overview

Begin a direct-to-cloud upload of a file. The server records the file metadata, splits the upload into parts, and returns presigned URLs that the client uploads each part to.
Direct-to-cloud file uploads support files up to 250 GB. However, Lenses and the Lens API do not support files larger than 512 MB.
The full direct-to-cloud upload flow is:
  1. Initiate the upload (this endpoint) — receive upload_id and presigned parts.
  2. PUT each part’s bytes directly to its presigned url. Capture the ETag response header from each PUT — that is the part’s part_token.
  3. Optionally, checkpoint completed parts so they can be skipped on resume.
  4. Optionally, generate fresh URLs for parts whose presigned URLs are about to expire.
  5. Complete the upload, supplying a part_token for each non-checkpointed part.
If something goes wrong, abort the upload to release server-side resources.
Part numbers are 1-based. The first part returned by this endpoint has part_number: 1, not 0. Using part_number: 0 in any subsequent call (/parts/urls, /parts/checkpoint, /complete) is rejected with 400 invalid_upload_parts.

​
Request Body

​
filename
string
required
Name of the file being uploaded
​
file_type
string
required
MIME type of the file (e.g. image/png, text/csv)
​
num_bytes
integer
required
Total size of the file in bytes
​
resume_if_started
boolean
When true, if a matching in-progress upload for this filename already exists for the organization, the server reuses it and returns only the parts that have not been checkpointed.“Matching” requires the existing record’s file_type and num_bytes to equal the request’s; a mismatch fails with 409. If no in-progress upload exists, behavior is identical to resume_if_started=false.

​
Response

​
upload_id
string
Server-generated identifier for the upload. Use it in subsequent calls to checkpoint, generate URLs, complete, or abort.
​
file_uid
string
Internal unique identifier that will be assigned to the completed file
​
file_name
string
Name of the file being uploaded
​
total_bytes
integer
Total size of the file in bytes
​
num_parts
integer
Number of parts the file has been split into
​
part_size
integer
Size in bytes used to split the file into parts. May be omitted for some upload backends.
​
integrity_algorithm
string
Whole-file checksum algorithm supported by the storage backend. One of crc32c or none. If crc32c, the client may compute a CRC32C over the full file and pass it as integrity_checksum on Complete Upload for server-side verification. If none, the backend does not support checksum verification — clients should not send one.
​
is_resume
boolean
true when the response reuses an existing in-progress upload (because the request specified resume_if_started=true and a matching record was found). false for a freshly created upload. When true, parts contains only the not-yet-checkpointed subset.
​
parts
array
Presigned descriptors for each part of the upload
curl -X POST https://api.u1.archetypeai.app/v0.5/files/uploads/initiate \
  -H "Authorization: Bearer $ATAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "training-data.parquet",
    "file_type": "application/x-parquet",
    "num_bytes": 1073741824,
    "resume_if_started": false
  }'

{
  "upload_id": "upl_1mehceg8cn80qsekh46143whrx",
  "file_uid": "fil_5hx819ysp38n2rt1f5fv0wsxgh",
  "file_name": "training-data.parquet",
  "total_bytes": 1073741824,
  "num_parts": 128,
  "part_size": 8388608,
  "integrity_algorithm": "crc32c",
  "is_resume": false,
  "parts": [
    {
      "part_number": 1,
      "url": "https://storage.example.com/upload/upl_1mehceg8cn80qsekh46143whrx/1?X-Amz-Signature=...",
      "offset": 0,
      "length": 8388608,
      "expires_at": "2026-04-28T15:32:18Z"
    },
    {
      "part_number": 2,
      "url": "https://storage.example.com/upload/upl_1mehceg8cn80qsekh46143whrx/2?X-Amz-Signature=...",
      "offset": 8388608,
      "length": 8388608,
      "expires_at": "2026-04-28T15:32:18Z"
    }
  ]
}