Skip to main content
POST
/
v1
/
namespaces
/
{namespace_name}
/
upload-url
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"}'

{
  "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"
}

​
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.
Use this endpoint for large files (up to 5GB). The pre-signed URL flow avoids API Gateway size limits.

​
How It Works

1

Step 1: Get Pre-signed URL

Call this endpoint with your desired file_name to get the upload URL
2

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
3

Step 3: Automatic Processing

After upload, the file is automatically processed through the document pipeline
The pre-signed URL expires in 15 minutes. Upload your file before it expires.

​
Step 1: Get Pre-signed URL

​
Authentication

​
x-api-key
string
required
Your API key for authentication
​
Content-Type
string
required
Must be application/json

​
Path Parameters

​
namespace_name
string
required
Name of the text namespace to upload files to

​
Body Parameters

​
file_name
string
required
Target filename including extension (e.g., document.pdf). Content-Type is auto-detected from the file extension.
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.
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"}'

{
  "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"
}

​
Response Fields

​
upload_url
string
Pre-signed S3 URL for uploading the file via PUT request
​
key
string
S3 object key where the file will be stored
​
content_type
string
Content-Type header to use when uploading (auto-detected from file_name)
​
expires_in
number
URL expiration time in seconds (default: 900 = 15 minutes)
​
method
string
HTTP method to use for upload (always PUT)
​
hint
string
Human-readable instructions for uploading the file

​
Step 2: Upload File to S3

Use the upload_url from the response above to upload your file directly to S3.
Upload File to S3
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:
ExtensionContent-Type
.pdfapplication/pdf
.docxapplication/vnd.openxmlformats-officedocument.wordprocessingml.document
.xlsxapplication/vnd.openxmlformats-officedocument.spreadsheetml.sheet
.jsonapplication/json
.txttext/plain
.csvtext/csv
.mdtext/markdown

​
S3 Upload Errors

403 - URL Expired
<Error>
  <Code>AccessDenied</Code>
  <Message>Request has expired</Message>
</Error>
If you receive the expired URL error, request a new pre-signed URL from Step 1.