> ## Documentation Index > Fetch the complete documentation index at: https://docs.ndi.nace.ai/llms.txt > Use this file to discover all available pages before exploring further. # read_file > Read the text of one uploaded file. **Cost class: fast.** ``path`` names an **uploaded source file** — the only namespace this tool serves. A workspace-internal path is refused with ``invalid_request`` naming the uploaded file to use instead. A file with several components (a spreadsheet's tabs, a pdf's sections) answers with their text concatenated in the file's own order, each part under a one-line header naming the component; ``components_returned`` and ``components_omitted`` report exactly what made it into the budget. Scope the read with ``component=`` (the names ``file_metadata`` lists) when only one tab or section matters, and with ``pages`` (1-based) for paged documents — spreadsheets have no pages, so scope those by component instead. Images are refused — ask about them with ``qa_file``. ## OpenAPI ````yaml /openapi.json post /v1/workspaces/{workspace_id}/tools/read-file openapi: 3.1.0 info: description: >- Document intelligence: parse, split, classify, extract, and ground files, or build a searchable workspace. Authenticate with ``X-API-Key``. title: NDI Platform API version: 0.1.0 servers: - url: https://ndi-api.nace.ai security: [] tags: [] paths: /v1/workspaces/{workspace_id}/tools/read-file: post: tags: - tools summary: read_file description: >- Read the text of one uploaded file. **Cost class: fast.** ``path`` names an **uploaded source file** — the only namespace this tool serves. A workspace-internal path is refused with ``invalid_request`` naming the uploaded file to use instead. A file with several components (a spreadsheet's tabs, a pdf's sections) answers with their text concatenated in the file's own order, each part under a one-line header naming the component; ``components_returned`` and ``components_omitted`` report exactly what made it into the budget. Scope the read with ``component=`` (the names ``file_metadata`` lists) when only one tab or section matters, and with ``pages`` (1-based) for paged documents — spreadsheets have no pages, so scope those by component instead. Images are refused — ask about them with ``qa_file``. operationId: read_file_v1_workspaces__workspace_id__tools_read_file_post parameters: - description: Workspace identifier. in: path name: workspace_id required: true schema: description: Workspace identifier. format: uuid title: Workspace Id type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/ReadFileRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/ReadFileResponse' description: Successful Response '504': content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: Gateway Timeout default: content: application/json: example: error: code: invalid_request detail: null message: >- Request body has extra fields that this operation does not accept. request_id: req-01j9k2n3p4q5r6s7t8v9 retryable: false schema: $ref: '#/components/schemas/ErrorEnvelope' description: >- Typed error envelope used by every 4xx and 5xx. ``error.code`` distinguishes the failure; HTTP status is a consequence of the code. security: - APIKeyHeader: [] components: schemas: ReadFileRequest: additionalProperties: false description: >- Request body for ``read-file``. ``path`` names an **uploaded source file** — the only namespace this tool serves. A workspace-internal derivative path is refused with ``invalid_request`` naming the uploaded file that owns it. ``component`` scopes the read to one public component by name — a spreadsheet tab or a pdf section, as listed by ``file-metadata``. ``pages`` is 1-based and selects on the file's absolute page numbers; out-of-range pages are ignored (absent from ``pages_returned``). Selected pages come back de-duplicated in document order, whatever order they were asked in. Spreadsheets have no pages — scope those with ``component`` instead. properties: component: anyOf: - type: string - type: 'null' title: Component max_chars: default: 200000 maximum: 1000000 minimum: 1 title: Max Chars type: integer pages: anyOf: - items: type: integer type: array - type: 'null' title: Pages path: title: Path type: string required: - path title: ReadFileRequest type: object ReadFileResponse: additionalProperties: false description: >- Response body for ``read-file``. A file with several components (a spreadsheet's tabs, a pdf's sections) answers with their text concatenated in the file's own order, each part prefixed by a one-line header naming the component. ``components_returned`` lists what contributed to ``content``; ``components_omitted`` lists components that were cut for size — the character budget ran out, or a part was too large to serve — or that have no text rendering at all (a query-only tab; ask it with ``qa-file``) — so an absent component is always visible, never a silently missing tab. Unnamed components (a recording, a raw upload) are listed by kind. properties: components_omitted: items: type: string title: Components Omitted type: array components_returned: items: type: string title: Components Returned type: array content: title: Content type: string file_id: format: uuid title: File Id type: string pages_returned: items: type: integer title: Pages Returned type: array path: title: Path type: string truncated: title: Truncated type: boolean required: - path - file_id - content - pages_returned - truncated - components_returned - components_omitted title: ReadFileResponse type: object ErrorEnvelope: description: Every non-2xx body on ``/v1``. example: error: code: invalid_request detail: null message: Request body has extra fields that this operation does not accept. request_id: req-01j9k2n3p4q5r6s7t8v9 retryable: false properties: error: $ref: '#/components/schemas/Error' required: - error title: ErrorEnvelope type: object Error: description: The error object, per spec 12 §1.8. properties: code: $ref: '#/components/schemas/ErrorCode' detail: anyOf: - additionalProperties: true type: object - type: 'null' description: Structured payload, when the code carries one. title: Detail message: description: Human- and model-readable; says what to do differently. title: Message type: string request_id: description: Per-request correlation id; matches the ``X-Request-Id`` header. title: Request Id type: string retryable: description: Whether retrying the identical request could succeed. title: Retryable type: boolean required: - code - message - retryable - request_id title: Error type: object ErrorCode: description: |- Every error the ``/v1`` surface can return. Clients must treat this as an **open** enum: a new member is an additive change (spec 12 §9), and a client that crashes on an unknown code makes every future error a breaking change. enum: - invalid_request - unsupported_file_type - file_too_large - invalid_schema - invalid_sql - invalid_path_prefix - command_not_permitted - batch_too_large - domain_validation_failed - default_label_required - wait_required_for_zero_retention - workspace_not_found - file_not_found - job_not_found - upload_not_found - node_not_found - schema_not_found - domain_not_found - session_not_found - access_label_not_found - path_conflict - schema_version_conflict - access_label_name_taken - workspace_name_taken - access_label_in_use - upload_expired - file_not_ingested - workspace_deleting - workspace_not_deletable - ingestion_in_progress - job_not_cancellable - confirmation_required - domain_not_published - domain_in_use - reserved_domain_slug - kg_not_built - kg_build_in_progress - session_busy - range_not_satisfiable - result_expired - access_denied - access_backstop_violation - access_mode_not_implemented - rate_limited - concurrency_limit_reached - quota_exceeded - corrupt_file - zero_byte_file - encrypted_file - parse_failed - ocr_failed - conversion_failed - sheetless_workbook - unplayable_media - unclassified_pages - job_cancelled - job_timeout - upstream_unavailable - internal_error - unauthorized - not_implemented title: ErrorCode type: string securitySchemes: APIKeyHeader: in: header name: X-API-Key type: apiKey ````