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-7d6c9f0a3b51",
  "file_uid": "1d4f9b2e-3a8c-4e1d-bb02-7d6c9f0a3b51",
  "file_name": "training-data.parquet",
  "total_bytes": 1073741824,
  "num_parts": 128,
  "part_size": 8388608,
  "is_resume": false,
  "parts": [
    {
      "part_number": 0,
      "url": "https://storage.example.com/upload/upl-7d6c9f0a3b51/0?X-Amz-Signature=...",
      "offset": 0,
      "length": 8388608,
      "expires_at": "2026-04-28T15:32:18Z"
    },
    {
      "part_number": 1,
      "url": "https://storage.example.com/upload/upl-7d6c9f0a3b51/1?X-Amz-Signature=...",
      "offset": 8388608,
      "length": 8388608,
      "expires_at": "2026-04-28T15:32:18Z"
    }
  ]
}

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.

​
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 250GB. 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.

​
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.
​
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-7d6c9f0a3b51",
  "file_uid": "1d4f9b2e-3a8c-4e1d-bb02-7d6c9f0a3b51",
  "file_name": "training-data.parquet",
  "total_bytes": 1073741824,
  "num_parts": 128,
  "part_size": 8388608,
  "is_resume": false,
  "parts": [
    {
      "part_number": 0,
      "url": "https://storage.example.com/upload/upl-7d6c9f0a3b51/0?X-Amz-Signature=...",
      "offset": 0,
      "length": 8388608,
      "expires_at": "2026-04-28T15:32:18Z"
    },
    {
      "part_number": 1,
      "url": "https://storage.example.com/upload/upl-7d6c9f0a3b51/1?X-Amz-Signature=...",
      "offset": 8388608,
      "length": 8388608,
      "expires_at": "2026-04-28T15:32:18Z"
    }
  ]
}