---
title: "Read a file"
method: POST
path: "/v1/workspaces/{id}/tools/read-file"
tags: ["Workspaces"]
---

# Read a file

`POST /v1/workspaces/{id}/tools/read-file`

## Request

- Base URL: `https://console.nace.ai`
- URL: `https://console.nace.ai/v1/workspaces/{id}/tools/read-file`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/nace/apis/drex-api/docs/v1/workspaces/:id/tools/read-file/post.ts> (a function with typed inputs; its response is checked against the schema)

The text of one ingested file: all of it, one tab or section (`component`), some pages (`pages`), or a span of lines of that text (`line_start`, `line_end`), up to `max_chars` characters. A file with several tabs or sections answers with each under a header line naming it; `components_omitted` lists any left out. `sql_tables` names the tables holding the rows of the long tables printed, to count or total with `run-sql`. File reads and SQL queries together are limited to 600 per account every 10 minutes. Free.

## Path parameters

- `id` string, required

## Headers

- `Idempotency-Key` string

## Request body

- ReadFileRequest
  - `path` string, required: The file's path in the workspace, as it was uploaded.
  - `pages` integer[], nullable: Pages to read, 1-based; leave it out for every page. Spreadsheets have no pages: name a tab with `component`.
  - `component` string, nullable: One tab or section to read; leave it out for the whole file.
  - `max_chars` integer: The most characters to return; past it, `truncated` is true.
  - `line_start` integer, nullable: The first line to return, 1-based, counted in the text this read returns without a line span. Leave it out for line 1.
  - `line_end` integer, nullable: The last line to return, inclusive. Leave it out for the last line.

## Response `200`

The answer.

- ReadFileResponse
  - `path` string, required
  - `file_id` string, required
  - `content` string, required: The text read. Each tab or section of a file with several starts with a header line naming it.
  - `pages_returned` integer[], required: The pages in `content`, in order; a page past the end is left out.
  - `truncated` boolean, required: True when `max_chars` cut the text.
  - `components_returned` string[], required: The tabs or sections in `content`.
  - `components_omitted` string[], required: The tabs or sections left out: cut for size, or with no text to read.
  - `sql_tables` string[]: The `run-sql` names of the tables holding the rows of the long tables in `content`: count, total or rank those rows there.
  - `line_start` integer, nullable: The first line returned, when the request named a span.
  - `line_end` integer, nullable: The last line returned, when the request named a span; null when `line_start` is past the end.
  - `line_count` integer, nullable: How many lines the whole text has, when the request named a span.
  - `table` ReadFileTable
    - `first_line` integer, required: The line of the table's header row.
    - `last_line` integer, required: The line of its last row.
    - `title` string, nullable, required: The text just above the table: its caption or units.
    - `header` string, required: The column names.
    - `rows` integer, nullable: For a table stored as one line, how many data rows it has.
  - `job_id` string, nullable: The job the call ran as; `GET /v1/documents/jobs/{id}` reads it.

## Other responses

- `401`: Missing or invalid API key (`authentication_error`, code `invalid_api_key`).
- `403`: The key can't read this file (`permission_error`, code `access_denied`).
- `404`: No workspace with this id that the key may use (`not_found_error`, code `workspace_not_found`), or Workspaces are off on this deployment (`not_found`).
- `422`: The body is invalid, or the document service refused it (`invalid_request_error`); the message says why. The workspace is checked first, so an id the key can't use answers `404` whatever the body.
- `429`: Over the account's requests per minute, or over 600 file reads and SQL queries per account every 10 minutes, together (`rate_limit_error`, code `rate_limited`).
- `500`: Something failed on Drex's side (`internal_error`).
- `502`: The document service refused Drex's own request (`upstream_error`, code `ndi_refused_drex`). Retry later.
- `503`: The document service is unavailable, or did not answer in time (`service_unavailable`). Retry with the same `Idempotency-Key`.
- `504`: The document service timed out (`upstream_error`). Retry with the same `Idempotency-Key`.

---

[API](https://skmtc.dev/nace/apis/drex-api.md) - [All operations](https://skmtc.dev/nace/apis/drex-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nace/apis/drex-api/revisions/a0e62d925a61?raw)