Skip to main content
POST
/
api
/
v1
/
files
/
upload-url
Generate File Upload URL
curl --request POST \
  --url https://api.wordsmith.ai/api/v1/files/upload-url \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "file_name": "<string>",
  "content_type": "<string>",
  "content_length": 123
}'
{
  "upload_url": "https://s3.amazonaws.com/wordsmith-uploads/signed-url-here",
  "upload_job_id": "123e4567-e89b-12d3-a456-426614174000",
  "expires_at": "2024-01-15T15:30:00Z"
}
Generates a presigned URL that can be used to upload files directly to Wordsmith’s storage. This is the first step when you want to include file attachments with your assistant questions.

​
Authentication

This endpoint requires a valid API key in the Authorization header.

​
Request Body

​
file_name
string
required
The name of the file to be uploaded, including the file extension
​
content_type
string
required
The MIME type of the file (e.g., “application/pdf”, “text/plain”, “application/vnd.openxmlformats-officedocument.wordprocessingml.document”, “image/png”, “audio/mp3”)
​
content_length
integer
The size of the file in bytes (optional but recommended)

​
Supported File Types

Wordsmith supports a wide variety of file formats including:
  • Documents: PDF, DOC, DOCX, TXT, MD, HTML
  • Spreadsheets: XLS, XLSX, CSV, TSV
  • Presentations: PPT, PPTX
  • Images: PNG, JPEG, WebP, TIFF
  • Audio: MP3, MP4, M4A, MPEG, WAV, WebM
  • Archives: ZIP
curl -X POST "https://api.wordsmith.ai/api/v1/files/upload-url" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "file_name": "contract.pdf",
    "content_type": "application/pdf",
    "content_length": 1048576
  }'

​
Response

​
upload_url
string
The presigned URL where you can upload your file using a PUT request
​
upload_job_id
string
The unique identifier for this upload job. Use this ID when creating assistant questions with file attachments.
​
expires_at
string
ISO 8601 timestamp indicating when the upload URL expires (typically 1 hour from creation)
{
  "upload_url": "https://s3.amazonaws.com/wordsmith-uploads/signed-url-here",
  "upload_job_id": "123e4567-e89b-12d3-a456-426614174000",
  "expires_at": "2024-01-15T15:30:00Z"
}

​
Complete Upload Flow

After receiving the upload URL, you need to upload your file: 
# Step 1: Get upload URL (shown above)
# Step 2: Upload the file
curl -X PUT "https://s3.amazonaws.com/wordsmith-uploads/signed-url-here" \
  -H "Content-Type: application/pdf" \
  --data-binary @contract.pdf

# Step 3: Use upload_job_id in your assistant question
curl -X POST "https://api.wordsmith.ai/api/v1/assistants/default/questions" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Please review this contract",
    "attachments": [
      {
        "upload_job_id": "123e4567-e89b-12d3-a456-426614174000"
      }
    ]
  }'

​
Error Responses

{
  "error": "Invalid file type",
  "status": 400
}

​
File Size Limits

  • Maximum file size: 50 MB per file
  • Maximum total attachments per question: 10 files
  • Files are automatically deleted after 30 days for security

​
Notes

  • Upload URLs expire after 1 hour
  • Files must be uploaded using a PUT request with the exact content type specified
  • The upload_job_id can be used immediately after uploading, no need to wait for processing