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

# Upload Base64 File

> Upload a file with base64-encoded contents via streaming multipart/form-data

<Note>
  **File Upload Note:** The interactive playground doesn't support file uploads due to browser limitations. Use the cURL examples below to test file uploads.
</Note>

## Overview

Upload a file whose contents have been Base64-encoded. The request body is `multipart/form-data`; the server decodes the Base64 payload as it streams.

Use this endpoint when the source environment cannot transmit raw binary contents (for example, embedding a small file in a JSON-bearing channel that has been wrapped in a multipart form).

For files larger than the simple-upload cap, or any case that needs resumable uploads, use the [direct-to-cloud multipart flow](./initiate-upload) (up to 250 GB) instead.

## Request

The request must be sent as `multipart/form-data` with a form field containing the base64-encoded file contents. The server decodes the contents on the fly.

### Supported File Types

The server's `Content-Type` validator accepts:

* **Images:** `image/jpeg`, `image/png`
* **Video:** `video/mp4`
* **Text & data:** `text/plain`, `text/csv`, `application/json`

JSONL (`application/x-ndjson`) is not accepted by this endpoint — use the [multipart flow](./initiate-upload) for JSONL.

**Maximum size:** 512 MB (after Base64 encoding). The Developer Console UI caps its uploads through this endpoint at 255 MB.

## Response

<ResponseField name="is_valid" type="boolean">
  Whether the upload was successful. Check this field to detect errors.
</ResponseField>

<ResponseField name="file_id" type="string">
  Filename of the uploaded file. Use this to download, delete, or fetch metadata for the file.
</ResponseField>

<ResponseField name="file_uid" type="string">
  Internal unique identifier for the uploaded file.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  # Encode the file first
  base64 -i /path/to/local/file.csv -o /tmp/file.b64

  curl -X POST https://api.u1.archetypeai.app/v0.5/files/base64 \
    -H "Authorization: Bearer $ATAI_API_KEY" \
    -F "file=@/tmp/file.b64;filename=file.csv"
  ```

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

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

  with open("/path/to/local/file.csv", "rb") as fh:
      encoded = base64.b64encode(fh.read())

  response = requests.post(
      "https://api.u1.archetypeai.app/v0.5/files/base64",
      headers={"Authorization": f"Bearer {api_key}"},
      files={"file": ("file.csv", io.BytesIO(encoded), "text/csv")},
  )

  result = response.json()
  if result.get("is_valid"):
      print(f"Uploaded: {result['file_id']}")
  else:
      print(f"Errors: {result.get('errors')}")
  ```

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

  const encoded = fs.readFileSync("/path/to/local/file.csv").toString("base64");

  const form = new FormData();
  form.append("file", new Blob([encoded]), "file.csv");

  const response = await fetch(
    "https://api.u1.archetypeai.app/v0.5/files/base64",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.ATAI_API_KEY}`,
      },
      body: form,
    }
  );

  const result = await response.json();
  if (result.is_valid) {
    console.log(`Uploaded: ${result.file_id}`);
  } else {
    console.error("Errors:", result.errors);
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Success theme={"system"}
  {
    "is_valid": true,
    "file_id": "file-abc123",
    "file_uid": "8f2c1e5a-7b3d-4d9e-9c1a-2f5b7d8e4a6c"
  }
  ```

  ```json 400 - Bad request theme={"system"}
  {
    "errors": [
      {
        "code": "invalid_base64",
        "message": "File contents are not valid base64.",
        "suggestion": "Ensure the form field contains correctly base64-encoded data.",
        "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 409 - File already exists theme={"system"}
  {
    "errors": [
      {
        "code": "file_already_exists",
        "message": "A file with this name already exists for the organization.",
        "suggestion": "Delete the existing file first or upload with a different filename.",
        "error_uid": "err-xxxxxxxx"
      }
    ]
  }
  ```
</ResponseExample>