---
title: "Read the text of a PDF"
method: POST
path: "/v1/text"
tags: ["text"]
---

# Read the text of a PDF

`POST /v1/text`

## Request

- Base URL: `https://api.niubai.vip` (the document declares no server; this is the origin it was published from)
- URL: `https://api.niubai.vip/v1/text`
- Auth: HTTP bearer

Every text span with its page, box, font and `span_id`, plus form fields, for the whole document or a page range. Use it to find what to edit and to scope an edit to one exact span (`scope.span_ids`). Free: reading does not bill pages.

## Request body

- TextRequest: ``POST /v1/text``'s body (spec §2.1). ``match`` is the engine's own ``MatchModel``, so ``query`` accepts exactly the four modes an edit's ``find`` does -- a caller searches with a string and then edits with the same string and the same ``match``.
  - `source` SourceModel, required
    - `url` string, uri, nullable
    - `file_id` string, nullable
    - `password` string, nullable
  - `query` string, nullable
  - `match` MatchModel
    - `mode` 'exact' | 'icase' | 'word' | 'regex'
    - `normalize` boolean
    - `across_lines` boolean
  - `pages` union
    - string
    - integer[]
  - `layers` string[]
  - `cursor` string, nullable
  - `limit` integer

## Response `200`

Successful Response

- TextResponse: ``POST /v1/text``'s body. ``next_cursor`` is present only when there is another page of results -- a cursor on the last page is an invitation to make one more empty request. ``fields`` only when ``layers`` included ``forms``.
  - `spans` TextSpanOut[]
    - `span_id` string, required
    - `page` integer, required
    - `page_label` string, nullable
    - `block_id` string, required
    - `line_id` string, required
    - `text` string, required
    - `bbox` number[]
    - `font` string
    - `size` number
    - `color` string
    - `dir` number[]
    - `is_ocr` boolean
    - `in_shared_xobject` boolean
    - `layer` string
    - `field` string, nullable
  - `page_count` integer
  - `next_cursor` string, nullable
  - `fields` FieldOut[], nullable
    - `name` string, nullable
    - `type` string
    - `value` string, nullable
    - `page` integer
    - `bbox` number[]
    - `xref` integer
    - `options` unknown[], nullable
      - unknown
    - `readonly` boolean

## Other responses

- `400`: error.code is one of: invalid_request
- `401`: error.code is one of: unauthorized
- `404`: error.code is one of: not_found
- `413`: error.code is one of: too_large
- `422`: error.code is one of: document_encrypted, document_unsupported, signed_document, edit_failed
- `429`: error.code is one of: rate_limited
- `500`: error.code is one of: engine_error
- `502`: error.code is one of: upstream_error
- `504`: error.code is one of: engine_timeout

---

[API](https://skmtc.dev/niubai/apis/pdf-edit-api-gateway.md) · [All operations](https://skmtc.dev/niubai/apis/pdf-edit-api-gateway/llms.txt) · [OpenAPI document](https://skmtc.dev/niubai/apis/pdf-edit-api-gateway/revisions/1ad0ce16ca04?raw)