> ## Documentation Index
> Fetch the complete documentation index at: https://wordsmithai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Import File

> Add a file to Wordsmith from a public URL.

> [!NOTE]
>
> **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](/preview).

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.

```bash cURL theme={null}
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"
  }'
```

```json Response theme={null}
{
  "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](/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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.