# Create Text File (/docs/api-reference/create_text_file)

`POST /v1/files/text` · operation `create_text_file`

Creates a text File (Markdown by default; or plain text, CSV, TSV or JSON) from up to 1 MiB of UTF-8 text. It's ready to read right away. Optionally add it to a Room or a Business. Needs edit access, as uploading does.

**Sign-in:** a signed-in person's access token (`Authorization: Bearer …`), which AI apps get through MCP sign-in; or a Workspace API key in the `X-SMB-API-Key` header.

### Headers

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `SMB-Workspace-Id` | string (uuid) | yes | Workspace where this operation runs. Required for user tokens and Workspace API keys. |
| `Idempotency-Key` | string | yes |  |

### Request body (JSON)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes |  |
| `content` | string | yes | Up to 1 MiB of UTF-8 text. Tabs and line breaks are fine; other control characters aren't. |
| `content_type` | one of `text/markdown`, `text/plain`, `text/csv`, `text/tab-separated-values`, `application/json` | no |  |
| `description` | string or null | no |  |
| `classification` | one of `financial`, `legal`, `operational`, `marketing`, `other`, `null` | no |  |
| `tags` | array of string | no |  |
| `business_id` | string | no | Stable SMB Business ID. |
| `room_id` | string | no | Stable Room ID. |
| `access_mode` | one of `inherit_room`, `restricted`, `private` | no | Who in the Room can open it; only with room_id. |
| `folder_id` | string or null | no | Room folder to put it in. |
| `summary` | string | no | Optional: what changed, in a few words. Shown with the version and in Room activity. |

### Response

**200** The existing resource or idempotent replay was returned. · **201** The resource was created.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `file` | object | yes |  |
| `file.file_id` | string | yes | Stable File ID. |
| `file.business_id` | string or null | yes | Associated Business, or null for a Workspace File. |
| `file.name` | string | yes |  |
| `file.description` | string or null | yes |  |
| `file.classification` | one of `financial`, `legal`, `operational`, `marketing`, `other`, `null` | yes |  |
| `file.tags` | array of string | yes |  |
| `file.origin` | one of `upload`, `artifact`, `legacy_document` | yes |  |
| `file.lifecycle` | one of `active`, `archived` | yes |  |
| `file.current_version` | object or null | yes |  |
| `file.revision` | integer | yes |  |
| `file.created_at` | string (date-time) | yes |  |
| `file.updated_at` | string (date-time) | yes |  |
| `file.archived_at` | string (date-time) or null | yes |  |
| `file.access_level` | one of `view`, `edit`, `full_access` | yes |  |
| `new_version` | object | yes |  |
| `new_version.file_version_id` | string | yes | Immutable File version ID. |
| `new_version.version_number` | integer | yes |  |
| `new_version.content_type` | string | yes |  |
| `new_version.size_bytes` | integer | yes |  |
| `new_version.sha256` | string or null | yes |  |
| `new_version.processing_status` | one of `pending_upload`, `processing`, `ready`, `quarantined`, `failed` | yes |  |
| `new_version.processing_error` | string or null | no | Upload processing failure code, when available. |
| `new_version.summary` | string or null | no | What changed in this version, when the author said. |
| `new_version.created_by` | object | no |  |
| `new_version.created_at` | string (date-time) | yes |  |
| `new_version.ready_at` | string (date-time) or null | yes |  |
| `new_version.protection` | object or null | no | What SMB's check for private numbers found: state, reason, items (kind and page, never a number), hidden. Null if unchecked. |
| `new_version.redacted_from` | string or null | no | Copy's original version. |
| `new_version.redacted_copy` | string or null | no | Original's redacted copy. |
| `action_receipt` | object | yes |  |
| `action_receipt.receipt_id` | string (uuid) | yes |  |
| `action_receipt.command_id` | string (uuid) | yes |  |
| `action_receipt.operation` | string | yes |  |
| `action_receipt.workspace_id` | string (uuid) | yes |  |
| `idempotent_replay` | boolean | yes |  |
| `request_id` | string | yes |  |
| `room_file` | object or null | yes | The File in the Room, when room_id was given. |

### Errors

- `400` The request is invalid.
- `401` Authentication is required.
- `403` The caller is not authorized.
- `404` The resource was not found.
- `409` The resource revision or idempotency input conflicts.
- `413` The request body is too large.
- `415` The request must be JSON.
- `422` Required evidence is missing.
- `429` Rate limit reached; honor Retry-After.
- `500` The request could not be completed.
- `502` A dependency returned an invalid response.
- `503` The service is temporarily unavailable.

### Example

```bash
curl --request POST "https://api.smb.co/v1/files/text" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "SMB-Workspace-Id: $WORKSPACE_ID" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --header "Content-Type: application/json" \
  --data '{"name":"…","content":"…"}'
```