> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moorcheh.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload File

> Get a pre-signed S3 URL to upload files directly, bypassing the 10MB API Gateway limit.

## Overview

Returns a pre-signed S3 PUT URL so you can upload files directly to S3. This bypasses API Gateway's 10MB limit and allows uploads up to 5GB.

<Info>
  Use this endpoint for large files (up to 5GB). The pre-signed URL flow avoids API Gateway size limits.
</Info>

## How It Works

<Steps>
  <Step title="Step 1: Get Pre-signed URL">
    Call this endpoint with your desired `file_name` to get the upload URL
  </Step>

  <Step title="Step 2: Upload File to S3">
    Use the `upload_url` with a PUT request, setting the `Content-Type` header to the `content_type` value from the response
  </Step>

  <Step title="Step 3: Automatic Processing">
    After upload, the file is automatically processed through the document pipeline
  </Step>
</Steps>

<Warning>
  The pre-signed URL expires in **15 minutes**. Upload your file before it expires.
</Warning>

***

## Step 1: Get Pre-signed URL

### Authentication

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`
</ParamField>

### Path Parameters

<ParamField path="namespace_name" type="string" required>
  Name of the text namespace to upload files to
</ParamField>

### Body Parameters

<ParamField body="file_name" type="string" required>
  Target filename including extension (e.g., `document.pdf`). Content-Type is auto-detected from the file extension.
</ParamField>

<Note>
  Preferred field names are snake\_case. Legacy camelCase (`fileName`) is still accepted for backward compatibility and returns deprecation headers (`Deprecation`, `Sunset`, `Warning`). CamelCase support is deprecated and scheduled for removal on **1 May 2026**.
</Note>

<RequestExample>
  ```bash Get Upload URL theme={null}
  curl -X POST "https://api.moorcheh.ai/v1/namespaces/my-documents/upload-url" \
    -H "x-api-key: your-api-key-here" \
    -H "Content-Type: application/json" \
    -d '{"file_name": "document.pdf"}'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - OK theme={null}
  {
    "upload_url": "https://s3.us-east-1.amazonaws.com/...",
    "key": "ownerId/namespace/document.pdf",
    "content_type": "application/pdf",
    "expires_in": 900,
    "method": "PUT",
    "hint": "Upload the file with: PUT <upload_url> with header Content-Type: application/pdf and body = file bytes"
  }
  ```

  ```json 400 - Bad Request (Missing file_name) theme={null}
  {
    "error": "file_name is required"
  }
  ```

  ```json 400 - Bad Request (Unsupported File Type) theme={null}
  {
    "error": "File type '.exe' is not supported. Allowed types: .pdf, .docx, .xlsx, .json, .txt, .csv, .md"
  }
  ```

  ```json 401 - Unauthorized theme={null}
  {
    "error": "Unauthorized: API key is required"
  }
  ```

  ```json 404 - Not Found theme={null}
  {
    "error": "Namespace 'example-namespace' not found"
  }
  ```
</ResponseExample>

### Response Fields

<ResponseField name="upload_url" type="string">
  Pre-signed S3 URL for uploading the file via PUT request
</ResponseField>

<ResponseField name="key" type="string">
  S3 object key where the file will be stored
</ResponseField>

<ResponseField name="content_type" type="string">
  Content-Type header to use when uploading (auto-detected from file\_name)
</ResponseField>

<ResponseField name="expires_in" type="number">
  URL expiration time in seconds (default: 900 = 15 minutes)
</ResponseField>

<ResponseField name="method" type="string">
  HTTP method to use for upload (always `PUT`)
</ResponseField>

<ResponseField name="hint" type="string">
  Human-readable instructions for uploading the file
</ResponseField>

***

## Step 2: Upload File to S3

Use the `upload_url` from the response above to upload your file directly to S3.

```bash Upload File to S3 theme={null}
curl -X PUT "<upload_url>" \
  -H "Content-Type: <content_type>" \
  --data-binary "@/path/to/document.pdf"
```

### Supported File Types

Use the corresponding `Content-Type` when uploading:

| Extension | Content-Type                                                              |
| --------- | ------------------------------------------------------------------------- |
| `.pdf`    | `application/pdf`                                                         |
| `.docx`   | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` |
| `.xlsx`   | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`       |
| `.json`   | `application/json`                                                        |
| `.txt`    | `text/plain`                                                              |
| `.csv`    | `text/csv`                                                                |
| `.md`     | `text/markdown`                                                           |

### S3 Upload Errors

```xml 403 - URL Expired theme={null}
<Error>
  <Code>AccessDenied</Code>
  <Message>Request has expired</Message>
</Error>
```

<Note>
  If you receive the expired URL error, request a new pre-signed URL from Step 1.
</Note>

## Related Endpoints

* [List Files](/api-reference/files/list-files) - List uploaded files in a namespace
* [Upload Text](/api-reference/data/upload-text) - Upload text content directly
* [Search](/api-reference/search/query) - Search uploaded files and documents
* [Get Documents](/api-reference/data/get-documents) - Retrieve document information