# Read File (/docs/api-reference/read_file)

`POST /v1/files/{file_id}/content` · operation `read_file`

Reads a File, 256 KiB at a time: text as UTF-8, a file SMB has read as its Markdown, others as base64. The first page's about has SMB's summary and metadata. Pass offset, then next_offset while has_more. Long text: outline, then section or query (far fewer tokens; gives revision). Big unread files: download_file or download_room_file.

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

### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `file_id` | string | yes | Stable File ID. |

### Headers

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

### Request body (JSON)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `file_version_id` | string | no | Immutable File version ID. |
| `offset` | integer | no | Text files: where to start, in bytes (next_offset from the last page). |
| `max_bytes` | integer | no | Text files: page size in bytes. Pages never split a character. |
| `outline` | boolean | no | Text: true returns the headings (section id, lines, tokens), not the text. |
| `section` | string | no | Text: one section, by outline id (s3) or heading. |
| `query` | string | no | Text: lines containing this, with line and section (20 at most). |

### Response

**200** Successful authorized response.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `file_content` | object | yes |  |
| `file_content.file_id` | string | yes | Stable File ID. |
| `file_content.file_version_id` | string | yes | Immutable File version ID. |
| `file_content.file_name` | string | yes |  |
| `file_content.content_type` | string | yes |  |
| `file_content.encoding` | one of `utf8`, `base64` | yes |  |
| `file_content.content` | string | yes |  |
| `file_content.size_bytes` | integer | yes | Bytes in this content: the whole file, or this page. |
| `file_content.total_bytes` | integer | yes | Size of the whole version in bytes. |
| `file_content.offset` | integer | yes | Where this content starts, in bytes. |
| `file_content.next_offset` | integer or null | yes | Pass as offset to read the next page; null at the end. |
| `file_content.has_more` | boolean | yes | Whether more of the file comes after this content. |
| `file_content.revision` | integer | no | With outline, section or query: expected_revision for edits. |
| `file_content.outline` | object | no |  |
| `file_content.section` | object | no |  |
| `file_content.matches` | array of object | no |  |
| `file_content.match_total` | integer | no | With query: all matching lines. |
| `file_content.about` | object | no |  |
| `request_id` | string | yes |  |

### 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/$FILE_ID/content" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "SMB-Workspace-Id: $WORKSPACE_ID" \
  --header "Content-Type: application/json" \
  --data '{}'
```