KERNIT Documentation

POST/hyperlink-scan

POST /hyperlink-scan

/hyperlink-scan reads a DOCX and returns review rows without writing links. It is the first step for reviewable integrations and the safest way to inspect a document before apply.

POST /hyperlink-scan

Scan a DOCX for reviewable links#

Reads a DOCX manuscript and returns citation, bibliography, DOI, figure, table, equation, section, appendix, algorithm, and listing review data without modifying the file.

AuthBearer API key BillingScan is review preparation and normally does not consume final apply allowance. Hosthttps://api.kernit.org

Contract Source#

This reference is backed by /docs/openapi.json. The source schema lives in app/docs/openapi.json, so request fields, response schemas, examples, and validation stay tied to one API contract.

Request Fields#

Defined by the OpenAPI contract requestBody multipart/form-data.

Field	Type	Required	Description
`file`	string:binary	Yes	Valid Microsoft Word DOCX package. Maximum size is 25 MB.
`settings`	string	No	JSON string matching HyperlinkSettings. Defaults are conservative.

Example Request#

curl -X POST https://api.kernit.org/hyperlink-scan \
  -H "Authorization: Bearer sk_kernit_live_YOUR_KEY" \
  -F "file=@paper.docx" \
  -F 'settings={"refs":true,"figures":"number","tables":"number","equations":"number","sections":"number","doi":true}'

Code Examples#

curl

curl -X POST https://api.kernit.org/hyperlink-scan \
  -H "Authorization: Bearer sk_kernit_live_YOUR_KEY" \
  -F "file=@paper.docx" \
  -F 'settings={"refs":true,"figures":"number","tables":"number","equations":"number","sections":"number","doi":true}'

JavaScript

const apiKey = 'sk_kernit_live_YOUR_KEY';
const form = new FormData();
form.append('file', fileInput.files[0]);
form.append('settings', "{\"refs\":true,\"figures\":\"number\",\"tables\":\"number\",\"equations\":\"number\",\"sections\":\"number\",\"doi\":true,\"crossref\":true}");

const response = await fetch('https://api.kernit.org/hyperlink-scan', {
  method: 'POST',
  headers: { Authorization: 'Bearer ' + apiKey },
  body: form
});

const text = await response.text();

Python

import requests

api_key = 'sk_kernit_live_YOUR_KEY'

with open('paper.docx', 'rb') as docx:
    response = requests.post(
        'https://api.kernit.org/hyperlink-scan',
        headers={'Authorization': f'Bearer {api_key}'},
        files={'file': ('paper.docx', docx, 'application/vnd.openxmlformats-officedocument.wordprocessingml.document')},
        data={
        'settings': "{\"refs\":true,\"figures\":\"number\",\"tables\":\"number\",\"equations\":\"number\",\"sections\":\"number\",\"doi\":true,\"crossref\":true}",
    },
    timeout=480
    )

print(response.status_code)
print(response.text)

Try This Endpoint#

Responses#

Status	Meaning	Schema
`200`	Review packet with scan token and candidate links.	`ScanPacket`
`400`	Invalid request shape, missing file, invalid JSON, or rejected DOCX.	`ErrorResponse`
`401`	Missing or invalid authorization.	`ErrorResponse`
`413`	DOCX exceeds the current 25 MB limit.	`ErrorResponse`
`default`	Unexpected KERNIT-side service error.	`ErrorResponse`

Example Success Body#

{
  "scanFingerprint": "sha256:2a71...",
  "scanToken": "eyJhbGciOiJIUzI1NiIs...",
  "summary": {
    "estimatedLinkCount": 47,
    "unmatchedCount": 3,
    "targetCount": 28
  },
  "matches": [
    {
      "refId": "r1",
      "sourceText": "[1]",
      "status": "ready",
      "targetId": "b1"
    }
  ],
  "targets": [
    {
      "targetId": "b1",
      "label": "Reference 1",
      "type": "reference"
    }
  ]
}

Error Examples#

400 Invalid request shape, missing file, invalid JSON, or rejected DOCX.

{
  "error": "Invalid JSON in form data"
}

401 Missing or invalid authorization.

{
  "error": "Missing authorization header"
}

413 DOCX exceeds the current 25 MB limit.

{
  "error": "File exceeds 25MB limit"
}

default Unexpected KERNIT-side service error.

{
  "error": "Processing failed"
}

Implementation Edge Cases#

Case	Expected handling
Malformed settings JSON	Return 400 and ask the caller to fix settings before scanning again. Do not apply defaults silently in an integration UI.
Invalid or damaged DOCX	Return 400 with a request-shape error. Ask the user to re-save the file in Word before retrying.
File over 25 MB	Return 413. Keep this as a file-size issue, not a scan-token or auth issue.
Ambiguous citation graph	Return matches with unmatched, low-confidence, held, or identity-change statuses so the reviewer can decide before apply.

Operational Notes#

Store scanToken and scanFingerprint with the review session.
Do not mutate settings before apply.
Expose low-confidence, unmatched, duplicate, and identity-changing rows first in your UI.

Settings Reference#

Field	Default	Description
citeStyle	auto	Detect numbered, author-date, superscript, or hybrid citation patterns.
refs	false	Link in-text citations to matching bibliography entries.
figures	number	Link figure mentions such as Fig. 2 or Figure 2 to captions.
tables	number	Link table mentions to table titles or captions.
equations	number	Link equation mentions such as Eq. (4) to equation targets.
sections	number	Link section references to numbered section headings.
appendices	number	Link appendix references to appendix targets.
doi	false	Detect DOI and URL text in references and convert it to external links.
crossref	false	Resolve references with Crossref evidence before applying DOI links.
refTitleLink	false	Use a resolved title as the hyperlink text when the reference contains DOI evidence.
linkColor	#0077BD	Set citation link color. Use auto to preserve source text color.
xrefLinkColor	#0077BD	Set non-citation cross-reference link color.
urlFont		Optional font override for DOI and URL links.
suffixDisambiguationOptIn	false	Enable suffix recalculation support for ambiguous author-year citations when available.

Was this page useful?Send a lightweight docs feedback event.

Last updated: May 12, 2026Canonical: https://kernit.org/docs/api/scan/