Create File

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

POST /api/v1/files

cURL

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"
  }'

Response

{
  "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"
}

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.

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.

cURL

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"
  }'

Response

{
  "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 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.