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

# Upload File

> Upload a file 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 to the Newton Platform for processing. The request body is `multipart/form-data` and the file contents are streamed to reduce memory usage.

The simple upload endpoint accepts files up to **512 MB**. For files above this — or for any case where you need resumable uploads — use the [direct-to-cloud multipart workflow](./initiate-upload) instead, which supports up to **250 GB**. The Developer Console UI caps its uploads through this endpoint at **255 MB**; client integrations can go up to the full 512 MB.

## Request

The request must be sent as `multipart/form-data` with the file contents in a form field. The exact form-field name depends on the client; most HTTP clients (e.g. `curl -F`, `requests` `files=`) will use the file's name as the field name.

### Required Header

* `Authorization: Bearer YOUR_API_KEY`
* `Content-Type: multipart/form-data` (automatically set by cURL's `-F` flag)

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

<Warning>
  **JSONL (`application/x-ndjson`) is rejected by this endpoint** despite appearing in the server's "supported types" error message. Use the [direct-to-cloud multipart flow](./initiate-upload) for JSONL — `initiate` accepts it as the `file_type`.
</Warning>

**Maximum size:** 512 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">
  The 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"}
  curl -X POST https://api.u1.archetypeai.app/v0.5/files \
    -H "Authorization: Bearer $ATAI_API_KEY" \
    -F "file=@/path/to/local/file.csv"
  ```

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

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

  with open("/path/to/local/file.csv", "rb") as fh:
      response = requests.post(
          "https://api.u1.archetypeai.app/v0.5/files",
          headers={"Authorization": f"Bearer {api_key}"},
          files={"file": ("file.csv", fh, "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 form = new FormData();
  form.append("file", new Blob([fs.readFileSync("/path/to/local/file.csv")]), "file.csv");

  const response = await fetch("https://api.u1.archetypeai.app/v0.5/files", {
    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_request",
        "message": "Multipart form is missing a file field.",
        "suggestion": "Include the file contents in a form field of the multipart request body.",
        "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"
      }
    ]
  }
  ```

  ```json 503 - Server at capacity theme={"system"}
  {
    "errors": [
      {
        "code": "server_at_capacity",
        "message": "Server is at capacity. Retry later.",
        "suggestion": "Retry the request after a short delay using exponential backoff.",
        "error_uid": "err-xxxxxxxx"
      }
    ]
  }
  ```
</ResponseExample>

<Tip>
  **Quick Test:** Navigate to your file's directory and run:

  ```bash theme={"system"}
  curl -X POST  https://api.u1.archetypeai.app/v0.5/files \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -F "file=@test_image.jpg"
  ```
</Tip>

<Note>
  **Getting Full Metadata:** This endpoint returns a minimal response. To get complete file information including size, dimensions, and timestamps, use the [Get File Metadata](/api-reference/files/get-metadata) endpoint.
</Note>

## Next Steps

1. **Get file details:**

```bash theme={"system"}
curl  https://api.u1.archetypeai.app/v0.5/files/metadata/YOUR_FILE_ID \
  -H "Authorization: Bearer YOUR_API_KEY"
```

2. **List all files:**

```bash theme={"system"}
curl  https://api.u1.archetypeai.app/v0.5/files/metadata \
  -H "Authorization: Bearer YOUR_API_KEY"
```

3. **Get storage summary:**

```bash theme={"system"}
curl  https://api.u1.archetypeai.app/v0.5/files/info \
  -H "Authorization: Bearer YOUR_API_KEY"
```