Skip to main content

PDFs & Chart Finder

List the workspace PDFs with the pages that hold charts, and scan a file to get the chart frames and process diagrams it contains, with polling states.

GET /v1/chart-to-data/pdfs lists the workspace's PDFs, newest first, each file once. Documents with the same file content collapse into the newest, and the older ones are listed in copies, because inputs and runs follow the file and not the document. sha256 is the file hash when it is known. pages lists the pages that have stored inputs with the number of charts the page's latest inputs name, and found carries chart counts from the file's finished scan, or null until one ran.

GET /v1/chart-to-data/pdfs/{documentId}/charts is the chart finder. The first request for a file queues a scan on a worker, and the route answers at once with the charts that already have stored inputs (state: "ready"). While the scan runs, status is queued or running; when it is done, charts also lists every chart frame the scan found (state: "found") and diagrams lists the process diagrams read on the scanned pages. Poll until status is done or failed. A scan by an older engine, or one that failed for a transient reason, is queued again on the next request; a deterministic failure stays.

Each chart entry has the page_number, a box in PDF points with a top-left origin, its state, and an id that stays stable across rescans: the chart key when one is stored, else the page and frame corner. ready charts have stored inputs and a chart_key; found ones were only seen by the scan. title is the title from the chart's latest reading and is absent or null for a chart never read. The scan covers the first pages of the file up to a configured limit, and pages_scanned and page_count report how far it went.

GET/v1/chart-to-data/pdfs

Response fields (data[])

document_iduuidThe newest document of the file.
sha256string | nullSHA-256 of the file when known; runs and inputs are bound to it.
namestringThe document name.
created_atstring (date-time)When the newest document was created.
tagsstring[]Document tags.
copiesuuid[]Older documents of the same file.
pages[]arrayPages with stored inputs: page_number and charts (how many charts the page's latest inputs name).
foundobject | nullChart counts from the file's finished scan, { charts, ready }; null until one ran.
GET/v1/chart-to-data/pdfs/{documentId}/charts

Response fields

document_iduuidThe document asked about.
statusstringThe state of the file's scan: queued, running, done or failed.
error_code, error_messagestring | nullSet when the scan failed.
page_countinteger | nullNull until the scan is done.
pages_scannedinteger0 until the scan is done.
charts[]arraypage_number, box { x, y, width, height }, state (ready or found), chart_key (nullable), id (stable across rescans) and title.
diagrams[]arraypage_number and view: reader (pipe, station, or null when the page holds no diagram), page { width, height }, nodes, edges and lanes.

Response: Scan done, one ready chart and one found chart

{
  "document_id": "d0e4b7a2-3f19-4c68-9a05-b1c7e8f26d34",
  "status": "done",
  "error_code": null,
  "error_message": null,
  "page_count": 12,
  "pages_scanned": 12,
  "charts": [
    {
      "page_number": 4,
      "box": { "x": 56.7, "y": 120.4, "width": 482.0, "height": 301.5 },
      "state": "ready",
      "chart_key": "p4-c1",
      "id": "p4-c1",
      "title": "Monthly output"
    },
    {
      "page_number": 7,
      "box": { "x": 56.7, "y": 98.0, "width": 482.0, "height": 340.2 },
      "state": "found",
      "chart_key": null,
      "id": "p7-56.7-98.0",
      "title": null
    }
  ],
  "diagrams": []
}
A diagram view lists nodes (id, label, kind, optional lane, boxes and evidence) and edges (from, to, kind, evidence). An edge is directed only when an arrowhead or the line order says which way the connection runs, and pipe diagrams add the drawn path as polylines of [x, y] points in PDF points. Otherwise directed is false.

Frequently asked questions

Why does the charts route list only some charts at first?+
The first request queues a scan, and until it is done only the charts that already have stored inputs are listed as ready. When status is done, charts also contains every frame the scan found, and diagrams contains the process diagrams of the scanned pages. Poll until done or failed.
Why do two documents appear as one PDF in the list?+
Inputs and runs are bound to the file hash, so documents with identical content are one PDF. The newest document is listed and the others appear in copies. Use either document id with the run routes; they resolve to the same file.
What does a 413 on the charts route mean?+
The document has no stored file hash and its file exceeds the size limit the chart reader accepts. The size limit is a deployment setting, so a smaller or re-exported PDF is the way forward.

Related

Chart Extraction Overview
Prepared Inputs
Queue & List Runs