Get File Download

Get a short-lived link that downloads a file’s original bytes.

GET /api/v1/files/{file_id}/download

cURL

# Get the link
curl "https://api.wordsmith.ai/api/v1/files/7c3e9a51-2d84-4f06-b1c7-5e9d0a2f8b63/download" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here"

# Download the file, with no Authorization header
curl -o contract.pdf "URL_FROM_THE_RESPONSE"

Response

{
  "file_id": "7c3e9a51-2d84-4f06-b1c7-5e9d0a2f8b63",
  "url": "https://wordsmith-files.s3.eu-west-1.amazonaws.com/a83f5c27-1e94-4b6d-8c02-d7e19b4f6a35?X-Amz-Signature=...",
  "file_name": "contract.pdf",
  "content_type": "application/pdf",
  "expires_at": "2026-10-13T11:05:41.318204Z"
}

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.

Returns a signed link to the file’s original bytes. The response is JSON, not a redirect.

Download the file with a plain GET to url and no Authorization header. The URL is already signed, and the storage host refuses a request that carries your API key. The link lasts at most 5 minutes, until expires_at, so fetch it straight away. Call this endpoint again for a fresh link.

A file is served only once its malware scan is clean. While the scan is still running, the response is 409 scan_in_progress; retry shortly. A file the scan flagged returns 404, as a missing file does.

Authentication

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

Path parameters

file_id · string (uuid) · required

The file’s id.

Response

file_id · string (uuid)

The file’s id.

url · string

The signed download link. Fetch it without an Authorization header.

file_name · string | null

The file’s name.

content_type · string | null

The file’s MIME type.

expires_at · string

When url stops working. ISO 8601 UTC, at most 5 minutes after the request.

cURL

# Get the link
curl "https://api.wordsmith.ai/api/v1/files/7c3e9a51-2d84-4f06-b1c7-5e9d0a2f8b63/download" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here"

# Download the file, with no Authorization header
curl -o contract.pdf "URL_FROM_THE_RESPONSE"

Response

{
  "file_id": "7c3e9a51-2d84-4f06-b1c7-5e9d0a2f8b63",
  "url": "https://wordsmith-files.s3.eu-west-1.amazonaws.com/a83f5c27-1e94-4b6d-8c02-d7e19b4f6a35?X-Amz-Signature=...",
  "file_name": "contract.pdf",
  "content_type": "application/pdf",
  "expires_at": "2026-10-13T11:05:41.318204Z"
}

Errors

See Errors for the error format.

HTTP Status	Error Code	When
401	unauthorized	The API key is missing or invalid.
403	mcp_not_enabled	Your organisation is not in the preview.
404	resource_not_found	The file does not exist, you cannot read it, or its malware scan flagged it.
409	scan_in_progress	The file’s malware scan has not finished. Retry shortly.