Skip to main content
POST
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

​
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.
​
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.
​
string (uuid)
The file’s id: the file_id other endpoints take.
​
string | null
The file’s name.
​
string | null
The file’s MIME type.
​
integer | null
Size in bytes.
​
string | null
When the file was created. ISO 8601 UTC.

​
Errors

See Errors for the error format.