Document Insights Retrieve API

Retrieve the signatures and table of contents found by the Document Insights API. Call this once the Status API reports processed.

Endpoint	/document-insights-retrieve
URL	https://llmwhisperer-api.us-central.unstract.com/api/v2/document-insights-retrieve
Method	GET
Headers	unstract-key: <YOUR API KEY>

Parameters

Parameter	Type	Default	Required	Description
whisper_hash	string		Yes	The whisper hash returned by the Document Insights API.

Example Curl Request

curl -X GET --location 'https://llmwhisperer-api.us-central.unstract.com/api/v2/document-insights-retrieve?whisper_hash=XXXXXXXXXXXXXXXXXXX' \
-H 'unstract-key: <Your API Key>'

info

To include the headers in the response use curl -i in the request.

Response

HTTP Status	Content-Type	Headers	Description
200	application/json		Signatures, table of contents and processing metadata. Refer below for JSON format.
400	application/json		Error while retrieving. Refer below for the error messages.
404	application/json		The job is unknown.

Example 400 Response

{
    "message": "<Error Message>"
}

Possible Error Messages

• Results not ready: <status message>: the document is still being processed. Check the Status API and try again.
• Results already retrieved: the result has already been retrieved once.
• Error in document insights extraction. Please retry the operation.: processing failed. Submit the document again.
• Job not found for the provided whisper hash '<whisper_hash>'
• Retrieval already in progress for this whisper hash: another request for the same whisper_hash is retrieving the result at the same time.
• Results not found in cache. Expired?: the result is no longer stored. Submit the document again.

Note: The result can be retrieved only once. Make sure to store it in your system if you need to access it multiple times. This is for security and privacy reasons. This behaviour can be controlled in on-prem installations.

Response data

{
    "signature_metadata": {
        "0": [],
        "1": [],
        "2": [
            {
                "type": "signature",
                "name": "Jane Doe",
                "desc": "Ink strokes in the field labelled 'Authorized Signature'; name taken from the 'Name:' field below it."
            }
        ]
    },
    "table_of_contents": [
        {
            "title": "Introduction",
            "page_number": "1",
            "level": 1,
            "numbering": "1.",
            "children": [
                {
                    "title": "Scope",
                    "page_number": "1",
                    "level": 2,
                    "numbering": "1.1",
                    "children": []
                }
            ]
        },
        {
            "title": "Payment Terms",
            "page_number": "2",
            "level": 1,
            "numbering": "2.",
            "children": []
        }
    ],
    "whisper_metadata": {
        "processed_page_count": 3,
        "total_page_count": 3,
        "avg_page_processing_time": 3.18,
        "mode": "document_insights",
        "input_tokens": 6420,
        "output_tokens": 512,
        "total_tokens": 6932,
        "cost": 0.000845
    },
    "webhook_metadata": "<webhook metadata, only when sent in the request>"
}

Signature Metadata

An object keyed by page. The keys are 0-based page indexes as strings, so "0" is the first page. Every processed page has a key. A page without signatures has an empty list.

Each signature has these fields:

Field	Type	Description
type	string	Always signature.
name	string or null	The signer's name, taken only from a nearby "Name:" or "Printed Name:" field. null if no name is available from such a field.
desc	string	The model's explanation of why it counted this as a signature. Useful for review, not meant to be parsed.

A signature is reported only when there is ink in a designated signature area. Empty signature lines, typed names and handwriting elsewhere on the page are not reported.

Table of Contents

A nested list of the section headings found in the document, in document order. Each entry has these fields:

Field	Type	Description
title	string	The heading text.
page_number	string	The page the heading is on, 1-based ("1" is the first page). Note that this differs from the 0-based keys in signature_metadata.
level	integer	The heading level. 1 is a top-level section, 2 a subsection, and so on.
numbering	string or null	The heading's numbering as printed, for example 1.1 or A.. null if the heading is not numbered.
children	list	The subsections under this heading, in the same format.

Repeating headers and footers, page numbers and the document title are not included. The table of contents is an empty list if no headings are found.

Whisper Metadata

Field	Type	Description
processed_page_count	integer	Number of pages processed. This is the number of pages counted toward your usage.
total_page_count	integer	Number of pages in the document.
avg_page_processing_time	float	Average processing time per page, in seconds.
mode	string	Always document_insights.
input_tokens	integer	Model input tokens used for the whole document.
output_tokens	integer	Model output tokens used for the whole document.
total_tokens	integer	Sum of input_tokens and output_tokens.
cost	float	Estimated model cost of the request in US dollars, for information only. Your usage is billed by page count.

Webhook Metadata

The webhook_metadata sent in the Document Insights API request, returned verbatim. The field is present only if webhook_metadata was sent.

Webhook delivery

If the request used use_webhook, the webhook receives the same JSON as the response above, with a payload_status object added:

{
  "payload_status": {
    "status": "success",
    "message": "",
    "whisper_hash": "<WHISPER_HASH>"
  },
  "signature_metadata": {},
  "table_of_contents": [],
  "whisper_metadata": {}
}

If processing fails, payload_status.status is error and the other fields are absent. Refer to the webhooks documentation for how webhooks are registered and retried.