> ## 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 /api/lens/query) with the Newton Fusion model (text, image, and video reasoning) or the Newton Omega encoder (time-series embeddings). ATAI_API_ENDPOINT is the base URL https://platform.u1.archetypeai.app with no version path; every endpoint path begins with /api. Pages whose descriptions are marked (Archived) document the legacy Lens runtime — do not use them for new projects.

# Download File Content

> Download the raw bytes of a file by its file_uid

Requires [version 2.0.0](https://docs.archetypeai.app/release-notes/2.0.x.md#v2-0-0) or later of the Archetype platform.

## Overview

This endpoint streams the raw contents of a file, looked up by the file's `file_uid` (a value
starting with `fil_`) instead of by its filename. It otherwise behaves like [Download
File](https://docs.archetypeai.app/api-reference/files/download-file.md).

The response carries `Content-Type` set to the stored file type, `Content-Length`, and a
`Content-Disposition: attachment` header with the file's name.

Only files whose status is `FILE_STATUS_REGISTERED` or `FILE_STATUS_INGESTED` can be downloaded.
A file that is still uploading or is corrupt returns an HTTP `409` error with the code
`file_not_available`. Files you can't see, files that are being deleted or are already deleted,
and values that aren't a `file_uid` return an HTTP `404` error.

## Path Parameters

**file\_id** `string` *required*

The file's `file_uid` (`fil_...`), as returned by the upload endpoints and in every file
metadata record.

## Header Parameters

**Range** `string`

A single byte range to download, as `bytes=first-last` (both inclusive; a `last` past the end
of the file stops at the end), `bytes=first-` (to the end of the file) or `bytes=-n` (the last
`n` bytes). A `Range` header with several ranges, a unit other than `bytes`, or a malformed
value is ignored, and the whole file is returned with `200`.

**If-Range** `string`

Serve `Range` only if the file's `ETag` is still exactly this value. Otherwise the range is
ignored and the whole current file is returned with `200`. Dates and weak tags never
match.

**If-Match** `string`

Download only if the file's `ETag` is one of these comma-separated values, or this is `*`.
Otherwise the response is `412` with the code `precondition_failed` and carries no file
content. `If-Match` is checked before `Range`, so a failed `If-Match` returns `412` even when
the range can't be satisfied.

## Response

The response body is the raw file bytes.

A satisfiable `Range` is answered with `206` and only the requested bytes, plus a
`Content-Range: bytes first-last/size` header. A range that starts at or past the end of the
file, or `bytes=-0`, returns `416` with the code `range_not_satisfiable` and a
`Content-Range: bytes */size` header.

Both `200` and `206` responses carry `Accept-Ranges: bytes` and an `ETag` that changes whenever
the file's content does. Treat the `ETag` as opaque. To resume an interrupted download, send the
`ETag` from the first response in `If-Range` along with a `Range` that starts where you
stopped.

```bash cURL theme={"system"}
curl https://platform.u1.archetypeai.app/api/files/fil_01k7x3q9m2v8n4p6r5t0w1y2z3/content \
  -H "Authorization: Bearer $ATAI_API_KEY" \
  -o downloaded_file.csv
```

```bash cURL - Resume theme={"system"}
# Fetch the rest of the file from byte 1048576. If the file changed since the first
# response, the server ignores Range and returns the whole file with 200 instead of 206.
curl https://platform.u1.archetypeai.app/api/files/fil_01k7x3q9m2v8n4p6r5t0w1y2z3/content \
  -H "Authorization: Bearer $ATAI_API_KEY" \
  -H "Range: bytes=1048576-" \
  -H 'If-Range: "<etag from the first response>"' \
  -o downloaded_file.part
```

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

api_key = os.environ.get("ATAI_API_KEY")
file_uid = "fil_01k7x3q9m2v8n4p6r5t0w1y2z3"

response = requests.get(
    f"https://platform.u1.archetypeai.app/api/files/{file_uid}/content",
    headers={"Authorization": f"Bearer {api_key}"},
    stream=True,
)
response.raise_for_status()

with open("downloaded_file.csv", "wb") as fh:
    for chunk in response.iter_content(chunk_size=1 << 20):
        fh.write(chunk)

print(f"Downloaded {file_uid}")
```

```javascript JavaScript theme={"system"}
import fs from "node:fs";
import { Readable } from "node:stream";

const fileUid = "fil_01k7x3q9m2v8n4p6r5t0w1y2z3";

const response = await fetch(
  `https://platform.u1.archetypeai.app/api/files/${fileUid}/content`,
  {
    headers: {
      Authorization: `Bearer ${process.env.ATAI_API_KEY}`,
    },
  }
);

if (!response.ok) {
  throw new Error(`Download failed: ${response.status}`);
}

const out = fs.createWriteStream("downloaded_file.csv");
Readable.fromWeb(response.body).pipe(out);
```

```text 200 - Success theme={"system"}
<binary file contents, with Content-Type set to the stored file type>
```

```text 206 - Partial content theme={"system"}
<the requested bytes; Content-Range: bytes 1048576-12483909/12483910>
```

```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 - File not found theme={"system"}
{
  "errors": [
    {
      "code": "not_found",
      "message": "File not found: org_id=<org_id>, file_id=fil_01k7x3q9m2v8n4p6r5t0w1y2z3",
      "suggestion": null,
      "error_uid": "err-xxxxxxxx"
    }
  ]
}
```

```json 409 - File not available theme={"system"}
{
  "errors": [
    {
      "code": "file_not_available",
      "message": "File is not available: status=UPLOADING",
      "suggestion": null,
      "error_uid": "err-xxxxxxxx"
    }
  ]
}
```

```json 412 - Precondition failed theme={"system"}
{
  "errors": [
    {
      "code": "precondition_failed",
      "message": "The file's current version does not match `If-Match`",
      "suggestion": "Get the file's current `ETag` and retry with it",
      "error_uid": "err-xxxxxxxx"
    }
  ]
}
```

```json 416 - Range not satisfiable theme={"system"}
{
  "errors": [
    {
      "code": "range_not_satisfiable",
      "message": "The requested range selects no byte of the file, which is 12483910 bytes long",
      "suggestion": "Request a non-empty range that starts before the end of the file",
      "error_uid": "err-xxxxxxxx"
    }
  ]
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.