---
title: "Cite numbers or phrases from a public document by page"
method: POST
path: "/cite"
---

# Cite numbers or phrases from a public document by page

`POST /cite`

## Request

- Base URL: `https://passage-data.com/api/v1`
- URL: `https://passage-data.com/api/v1/cite`
- Auth: one of:
  - none
  - HTTP bearer
  - API key in header `x-api-key`

A public document sent here is kept in our library, to be indexed and read into cited rows; a link on a file-sharing host or carrying a signature or token is read and never kept (`kept` says which, and why). Each `find` is located on the document's own page text, exactly as typed (a number as printed: 0.10 is not 0.1, a decimal comma reads as a point; spaces optional; any case; µg read as ug), and answered with every page it is printed on (`n_hits`, the first 5 with their `quote` and `cite`: page, address, the document's sha256, the day read). A find not printed on the pages read is in `not_found`. `held_as` names the instruments this server reads rows from when the document is one of them. PDFs, web pages and plain text up to 40 MiB; a scan with no text layer is refused (read.no_text).

## Request body

- object
  - `url` string, required
  - `find` string[], required

## Response `200`

Each find with its pages and quotes; or a `refused` block from reading the document (read.http_<status>, read.unreachable, read.private_host, read.kind_unread, read.no_text, read.damaged, read.failed, engine.timeout, engine.unreachable)

- object
  - `url` string
  - `final_url` string
  - `sha256` string
  - `bytes` integer
  - `kind` 'pdf' | 'html' | 'text'
  - `n_pages` integer
  - `title` string
  - `fetched_at` string
  - `found` object[]
    - `find` string
    - `n_hits` integer
    - `hits` object[]
      - `page` integer
      - `printed` string
      - `quote` string
      - `cite` string
  - `not_found` object[]
    - `find` string
    - `says` string
  - `says` string
  - `kept` object
    - `kept` boolean
    - `why` string
  - `held_as` object[]
  - `next` string
  - `refused` Refused
    - `refused` object
      - `code` string
      - `says` string

## Other responses

- `400`: url.missing, url.malformed, find.missing, find.too_many, read.bad_address
- `413`: read.too_large (over 40 MiB)
- `429`: cite.daily_cap: the door's reads for the UTC day are spent; nothing was opened
- `503`: cite.not_configured

---

[API](https://skmtc.dev/passage-data/apis/passage-data-cited-environmental-limits.md) · [All operations](https://skmtc.dev/passage-data/apis/passage-data-cited-environmental-limits/llms.txt) · [OpenAPI document](https://skmtc.dev/passage-data/apis/passage-data-cited-environmental-limits/revisions/ba066708bf53?raw)