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

import requests

url = "https://api.wordsmith.ai/api/v1/files/upload-url"

payload = {
    "file_name": "<string>",
    "content_type": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({file_name: '<string>', content_type: '<string>'})
};

fetch('https://api.wordsmith.ai/api/v1/files/upload-url', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.wordsmith.ai/api/v1/files/upload-url",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'file_name' => '<string>',
    'content_type' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.wordsmith.ai/api/v1/files/upload-url"

	payload := strings.NewReader("{\n  \"file_name\": \"<string>\",\n  \"content_type\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.wordsmith.ai/api/v1/files/upload-url")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"file_name\": \"<string>\",\n  \"content_type\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.wordsmith.ai/api/v1/files/upload-url")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"file_name\": \"<string>\",\n  \"content_type\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "upload_url": "https://s3.amazonaws.com/wordsmith-uploads/signed-url-here",
  "job_id": "123e4567-e89b-12d3-a456-426614174000",
  "content_type": "application/pdf"
}

POST

api

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

import requests

url = "https://api.wordsmith.ai/api/v1/files/upload-url"

payload = {
    "file_name": "<string>",
    "content_type": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({file_name: '<string>', content_type: '<string>'})
};

fetch('https://api.wordsmith.ai/api/v1/files/upload-url', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.wordsmith.ai/api/v1/files/upload-url",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'file_name' => '<string>',
    'content_type' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.wordsmith.ai/api/v1/files/upload-url"

	payload := strings.NewReader("{\n  \"file_name\": \"<string>\",\n  \"content_type\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.wordsmith.ai/api/v1/files/upload-url")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"file_name\": \"<string>\",\n  \"content_type\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.wordsmith.ai/api/v1/files/upload-url")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"file_name\": \"<string>\",\n  \"content_type\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "upload_url": "https://s3.amazonaws.com/wordsmith-uploads/signed-url-here",
  "job_id": "123e4567-e89b-12d3-a456-426614174000",
  "content_type": "application/pdf"
}

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 agent questions, or attach files to a task.

Authentication

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

Request Body

string

required

The name of the file to be uploaded, including the file extension

string

required

The MIME type of the file (e.g., “application/pdf”, “text/plain”, “application/vnd.openxmlformats-officedocument.wordprocessingml.document”, “image/png”, “audio/mp3”)

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, HEIC, HEIF
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"
  }'

const response = await fetch(
  "https://api.wordsmith.ai/api/v1/files/upload-url",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer sk-ws-api1-your_api_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      file_name: "contract.pdf",
      content_type: "application/pdf",
    }),
  }
);

const uploadInfo = await response.json();

import requests

headers = {
    "Authorization": "Bearer sk-ws-api1-your_api_key_here",
    "Content-Type": "application/json"
}

data = {
    "file_name": "contract.pdf",
    "content_type": "application/pdf"
}

response = requests.post(
    "https://api.wordsmith.ai/api/v1/files/upload-url",
    headers=headers,
    json=data
)
upload_info = response.json()

Response

string

The presigned URL where you can upload your file using a PUT request.

string

The unique identifier for this upload job. After you upload the file, pass it as upload_job_id in an agent question’s attachments, or as upload_job_id in attachments when you attach files to a task or add a task comment or thread reply. Each job_id can be used once.

string

The MIME type that was specified in the request.

{
  "upload_url": "https://s3.amazonaws.com/wordsmith-uploads/signed-url-here",
  "job_id": "123e4567-e89b-12d3-a456-426614174000",
  "content_type": "application/pdf"
}

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 agent question
curl -X POST "https://api.wordsmith.ai/api/v1/agents/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"
      }
    ]
  }'

// Step 1: Get upload URL
const uploadResponse = await fetch(
  "https://api.wordsmith.ai/api/v1/files/upload-url",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer sk-ws-api1-your_api_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      file_name: "contract.pdf",
      content_type: "application/pdf",
    }),
  }
);

const { upload_url, job_id } = await uploadResponse.json();

// Step 2: Upload the file
const fileUploadResponse = await fetch(upload_url, {
  method: "PUT",
  headers: {
    "Content-Type": "application/pdf",
  },
  body: fileBlob,
});

// Step 3: Use in agent question
const questionResponse = await fetch(
  "https://api.wordsmith.ai/api/v1/agents/default/questions",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer sk-ws-api1-your_api_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      question: "Please review this contract",
      attachments: [{ upload_job_id: job_id }],
    }),
  }
);

Error Responses

See the Errors page for the full error format reference.

{
  "error_code": "invalid_request_body",
  "ws_api_error_code": "invalid_request_body",
  "message": "Request body is invalid. Ensure it is valid JSON with 'file_name' and 'content_type' fields."
}

{
  "error_code": "unauthorized",
  "ws_api_error_code": "unauthorized",
  "message": "Invalid API key"
}

File Size Limits

Maximum file size: 1 GB per file. A larger file is refused with upload_too_large when it is attached
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
Pass the job_id as upload_job_id in attachments, on agent questions and on the task file, comment and thread reply endpoints
Each job_id can be used once. Using it creates the file; the task response lists the new file’s id

API Documentation

Agents

Assistants (deprecated)

Tasks

Directory

Generate File Upload URL

Authentication

Request Body

Supported File Types

Response

Complete Upload Flow

Error Responses

File Size Limits

Notes

​Authentication

​Request Body

​Supported File Types

​Response

​Complete Upload Flow

​Error Responses

​File Size Limits

​Notes

Authentication

Request Body

Supported File Types

Response

Complete Upload Flow

Error Responses

File Size Limits

Notes