> ## 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.

# Create File

> Save text as a plain text, Markdown or Word file.

> [!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).

Stores text you send as a new file in your private space. The response's `id` is the new file's `file_id`.

`format` picks the file type:

| `format` | Stored as | `content_type` |
| - | - | - |
| `txt` | Plain text, as sent | `text/plain` |
| `md` | Markdown, as sent | `text/markdown` |
| `docx` | A Word document converted from `content` as Markdown | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` |

Wordsmith adds the extension when `file_name` does not already end with it, ignoring case. `"Summary"` with `docx` is stored as `Summary.docx`.

`content` is at most 1,000,000 bytes as UTF-8.

## 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

**file\_name** `string` *required*

The file's name. The extension for format is added when the name does not end with it. 1 to 255 characters.

**content** `string` *required*

The file's text, at most 1,000,000 bytes as UTF-8.

**format** `string` *required*

`txt` stores plain text, `md` stores Markdown, and `docx` converts the content from Markdown to a Word document.

## 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 stored name, with the extension added if it was missing.

**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" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "file_name": "Termination summary",
    "content": "# Termination rights\n\nEither party may terminate on 30 days written notice.",
    "format": "docx"
  }'
```

```json Response theme={null}
{
  "id": "5d91b7e3-a4c2-4e86-9f1d-0b8c3e6a2f54",
  "file_name": "Termination summary.docx",
  "content_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
  "content_length": 9873,
  "created_at": "2026-10-13T10:31:05.741000Z"
}
```

## Errors

See [Errors](/errors) for the error format.

| HTTP Status | Error Code | When |
| - | - | - |
| 400 | `invalid_request_body` | The body is not valid JSON, misses a field, has an unknown field, `format` is not `txt`, `md` or `docx`, or `file_name` is empty or over 255 characters. |
| 400 | `upload_too_large` | `content` is over 1,000,000 bytes as UTF-8. `size_limit_bytes` gives the limit. |
| 400 | `unsupported_file_type` | Wordsmith could not convert `content` to a Word document. |
| 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. |
| 503 | `temporarily_unavailable` | The document converter is busy or unavailable. Retry shortly. |


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