KERNIT Documentation
POST
/hyperlink-crossrefPOST /hyperlink-crossref
/hyperlink-crossref resolves bibliography entries against Crossref evidence and returns DOI/title metadata that can be reviewed before final hyperlink application.
POST
/hyperlink-crossref
Resolve bibliography entries with Crossref evidence#
Extracts references from the DOCX, resolves DOI/title evidence, detects CSL style signals when enabled, and returns resolver metadata that can be reviewed before apply. Heavy resolver calls can stream progress before the terminal JSON report.
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 DOCX file to inspect. |
settings | string | No | JSON string matching HyperlinkSettings. Set doi and crossref true for resolver work. |
scanFingerprint | string | No | Fingerprint returned by /hyperlink-scan. Recommended so resolver output aligns with apply. |
Example Request#
curl -X POST https://api.kernit.org/hyperlink-crossref \
-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}' \
-F "scanFingerprint=..."Code Examples#
curl
curl -X POST https://api.kernit.org/hyperlink-crossref \
-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}' \
-F "scanFingerprint=..."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}");
form.append('scanFingerprint', "sha256:...");
const response = await fetch('https://api.kernit.org/hyperlink-crossref', {
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-crossref',
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}",
'scanFingerprint': "sha256:...",
},
timeout=480
)
print(response.status_code)
print(response.text)Try This Endpoint#
Responses#
| Status | Meaning | Schema |
|---|---|---|
200 | Resolver report with DOI/title evidence, scan state, and optional style-detection metadata. | ResolverReport |
400 | Invalid request shape, missing file, invalid JSON, or rejected DOCX. | ErrorResponse |
401 | Missing or invalid authorization. | ErrorResponse |
403 | Authenticated caller does not have access. | ErrorResponse |
413 | DOCX exceeds the current 25 MB limit. | ErrorResponse |
503 | KERNIT server-side processing is temporarily unavailable or the resolver stream failed. | ErrorResponse |
default | Unexpected KERNIT-side service error. | ErrorResponse |
Example Success Body#
{
"scanFingerprint": "sha256:2a71...",
"scanToken": "eyJhbGciOiJIUzI1NiIs...",
"resolvedWorks": {
"r1": {
"doi": "10.1234/example",
"title": "Example resolved article",
"confidence": 0.94,
"citationImpact": "link-only-safe"
}
},
"references": [
{
"refId": "r1",
"index": 1,
"refText": "Example Author. Example resolved article. Journal. 2024.",
"existingDoi": null
}
]
}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"
}403 Authenticated caller does not have access.
{
"error": "hyperlinker_requires_paid_plan"
}413 DOCX exceeds the current 25 MB limit.
{
"error": "File exceeds 25MB limit"
}Implementation Edge Cases#
| Case | Expected handling |
|---|---|
| Resolver stream has progress but no terminal result | Treat the response as incomplete. Keep the raw response, request time, and scanFingerprint for support. |
| Resolver evidence changes reference identity | Expose link-only or review-required decisions instead of applying a title or DOI change automatically. |
| Crossref or resolver availability fails | Treat 5xx/503 as KERNIT-side availability. Do not tell users to tune local client capacity. |
| Missing scanFingerprint | Allowed for lookup, but production integrations should include it so resolver evidence aligns with the scan/apply state. |
Use Cases#
- Find DOI URLs for references that contain incomplete DOI text.
- Validate reference identity before linking the title or DOI.
- Expose confidence and citation-impact warnings to reviewers.
Response Notes#
The endpoint can stream progress and then return a terminal resolver report. If the resolver returns a 5xx response, treat it as a KERNIT-side processing availability condition rather than a client-side integration fix.
FAQ
- Is Crossref resolution mandatory?
- No. Internal citation and cross-reference links can be reviewed and applied without DOI resolution.
- Should resolved title changes be automatic?
- No. Treat identity-changing resolver evidence as review-required unless your workflow has an explicit approval model.
Was this page useful?Send a lightweight docs feedback event.