Import File

Add a file to Wordsmith from a public URL.

POST /api/v1/files/import

cURL

curl -X POST "https://api.wordsmith.ai/api/v1/files/import" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/templates/mutual-nda.docx",
    "file_name": "Mutual NDA.docx"
  }'

Response

{
  "id": "e2a6c4d8-91b3-4f7e-8d05-3c6b9a1f2e47",
  "file_name": "Mutual NDA.docx",
  "content_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
  "content_length": 38412,
  "created_at": "2026-10-13T10:02:47.208000Z"
}

Preview. This endpoint is available to organisations in the Wordsmith MCP and files pilot. Other organisations receive 403 mcp_not_enabled. See the preview overview.

Downloads the file at a public URL and stores it in your private space. The response’s id is the new file’s file_id.

The URL must be public https. Wordsmith refuses private and internal addresses. The file must be 100 MB or smaller, and the whole download, redirects included, must finish within 20 seconds. A refused download is a 400 that says why, without naming the address Wordsmith resolved.

Without file_name, the file takes the name in the server’s Content-Disposition header, or else the last segment of the URL.

Authentication

Send an API key, or an OAuth access token with the files:write scope, as a bearer token in the Authorization header. A token without the scope gets 403 with "error": "insufficient_scope".

Body parameters

url · string · required

A public https URL to download. The file must be 100 MB or smaller and download within 20 seconds. At most 2,048 characters.

file_name · string

The name to store the file under. Defaults to the name the server sends, or the URL’s last segment. 1 to 255 characters.

Response

Returns 201 with the new file.

id · string (uuid)

The file’s id: the file_id other endpoints take.

file_name · string | null

The file’s name.

content_type · string | null

The file’s MIME type.

content_length · integer | null

Size in bytes.

created_at · string | null

When the file was created. ISO 8601 UTC.

cURL

curl -X POST "https://api.wordsmith.ai/api/v1/files/import" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/templates/mutual-nda.docx",
    "file_name": "Mutual NDA.docx"
  }'

Response

{
  "id": "e2a6c4d8-91b3-4f7e-8d05-3c6b9a1f2e47",
  "file_name": "Mutual NDA.docx",
  "content_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
  "content_length": 38412,
  "created_at": "2026-10-13T10:02:47.208000Z"
}

Errors

See Errors for the error format.

HTTP Status	Error Code	When
400	invalid_request_body	The body is not valid JSON, misses url, has an unknown field, or a field is out of range.
400	bad_request	Wordsmith would not or could not download the URL. It is not public https, its host was not found, the connection failed, it redirected in a loop or too many times, it did not answer 200, or it took over 20 seconds. message says which.
400	upload_too_large	The file is over 100 MB. size_limit_bytes gives the limit.
401	unauthorized	The API key is missing or invalid.
403	forbidden	Your user is not allowed to upload files.
403	mcp_not_enabled	Your organisation is not in the preview.