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

# Get File

> Retrieve the metadata 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 returns the metadata record of one file, looked up by the file's `file_uid` (a
value starting with `fil_`) instead of by its filename. It returns the same record as [Get File
Metadata](https://docs.archetypeai.app/api-reference/files/get-metadata.md).

A file's `file_uid` never refers to any other file. If you delete a file and upload a new one
under the same filename, the new file gets a new `file_uid`, so a stored `file_uid` can't
accidentally point at the replacement.

Files you can't see, files that are being deleted or are already deleted, and values that aren't
a `file_uid` all 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.

## Response

Returns the file's metadata record. See [Get File Metadata](https://docs.archetypeai.app/api-reference/files/get-metadata.md) for the full
description of each field.

**file\_id** `string`

The filename the file was uploaded under

**file\_uid** `string`

The file's unique identifier (`fil_...`)

**file\_type** `string`

MIME type of the file (e.g. `image/png`, `text/csv`)

**num\_bytes** `integer`

Size of the file in bytes

**created\_at** `string`

The date and time at which the file was created, in [RFC
3339](https://datatracker.ietf.org/doc/html/rfc3339) format

**file\_status** `string`

Lifecycle status of the file

**file\_attributes** `object`

Type-specific attributes for the file

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

```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}",
    headers={"Authorization": f"Bearer {api_key}"},
)

print(response.json())
```

```javascript JavaScript theme={"system"}
const fileUid = "fil_01k7x3q9m2v8n4p6r5t0w1y2z3";

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

const metadata = await response.json();
console.log(metadata);
```

```json 200 - Success theme={"system"}
{
  "file_id": "test_image.png",
  "file_uid": "fil_01k7x3q9m2v8n4p6r5t0w1y2z3",
  "is_valid": true,
  "file_type": "image/png",
  "num_bytes": 482931,
  "created_at": "2026-10-21T09:12:44Z",
  "file_status": "FILE_STATUS_INGESTED",
  "file_attributes": {
    "width": 1920,
    "height": 1080,
    "num_channels": 3,
    "channel_bands": ["R", "G", "B"]
  },
  "ingested": true,
  "file_index": 0,
  "file_tags": {}
}
```

```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"
    }
  ]
}
```


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