RefRight API Reference
A REST API for parsing, converting, verifying, and enriching academic references. Paste any raw citation text and get back perfectly formatted output in APA 7, MLA 9, JATS XML, BibTeX, and more — in a single POST call.
Base URL: https://your-domain.com/refright
All endpoints are relative to this base. Replace with your deployment URL or use http://localhost:3005/refright for local development.
Authentication
All API requests (except the public guest demo) require an API key passed in the X-API-Key HTTP header. Get your key from the Dashboard after signing up.
X-API-Key: rr_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Never expose your API key in client-side JavaScript or public repositories. Treat it like a password. You can revoke and regenerate keys from your dashboard at any time.
Quick Start
/api/parse with your key and chosen style. You'll get structured JSON + formatted output back in under a second.curl -X POST https://your-domain.com/refright/api/parse \ -H "X-API-Key: rr_live_xxxx" \ -H "Content-Type: application/json" \ -d '{ "references": "Smith J, Jones K. mRNA vaccines. N Engl J Med. 2022;387:1302.", "referenceStyle": "apa7", "format": "txt" }'
Pricing & Credits
RefRight uses a prepaid credit system. 1 INR = 10 credits. Credits are deducted per reference, per successful parse only.
DOI enrichment is free. Enabling lookupDoi or fillMissing does not cost extra credits — only the base parse cost applies.
Rate Limits
Limits apply per API key per minute. Exceeding the limit returns 429 Too Many Requests. Implement exponential back-off and retry logic in your integration.
| Plan | Requests / min | Max refs / request |
|---|---|---|
| Pay As You Go | 60 | 100 |
| Starter | 60 | 100 |
| Pro | 120 | 100 |
| Enterprise | Custom | 100 |
Errors
RefRight uses standard HTTP status codes. Every error response is JSON with an error string field.
| Status | Meaning | Common cause |
|---|---|---|
| 400 | Bad Request | Missing references field, unsupported format, or invalid sourceType |
| 401 | Unauthorized | Missing or invalid X-API-Key header |
| 402 | Payment Required | Insufficient credits — top up your account to continue |
| 429 | Too Many Requests | Rate limit exceeded for your plan |
| 500 | Server Error | Unexpected internal error — retry with back-off |
{
"error": "Insufficient prepaid credits. Please purchase additional credits to continue.",
"currentCreditBalance": 2,
"shortage": 1
}
POST /api/parse
The core endpoint. Accepts one or more raw references (or structured input like BibTeX / RIS) and returns formatted, structured output in any supported style and format. Also runs optional CrossRef + PubMed DOI enrichment.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| references | string | Required |
The reference text to parse. Multiple references must be separated by a blank line. Also accepts BibTeX, RIS, or LaTeX bibliography content — set sourceType accordingly.
|
| format | string | Optional |
Output format. See Output Formats for full list. Default: "json"
|
| referenceStyle | string | Optional |
Citation style ID. Use a built-in style ID or a custom style name from your account. Omit or use "auto" for no style applied.Options: apa7 · mla9 · chicago · chicago-author-date · harvard · ieee · vancouver · ama
|
| sourceType | string | Optional |
Input format of the references field.Options: references (default) · bibtex · ris · bbl · latex-list
|
| lookupDoi | boolean | Optional |
When true, verifies and auto-corrects DOIs via CrossRef. Falls back to PubMed for journal/article types that CrossRef can't match.Default: false · No extra credit cost
|
| fillMissing | boolean | Optional |
When true, auto-fills missing volume, issue, pages and expands et al. to full author list from CrossRef metadata. Requires a valid DOI (or lookupDoi: true).Default: false
|
Response
"format": string// echo of requested format
"output": string// formatted output in requested format
"referenceCount": number// number of references parsed
"creditsConsumed": number// credits deducted for this request
"parsedData": ParsedEntry[]// structured data per reference
"doiReport": DoiReport | null// present when lookupDoi=true
"doiValidations": DoiValidation[]// per-entry DOI detail, when lookupDoi=true
}
ParsedEntry object
"authors": string[]// e.g. ["Smith, John A", "Jones, Karen B"]
"year": string
"title": string
"journal": string
"type": string// "article-journal" | "book" | "chapter" | "preprint" …
"doi": string
"inTextCitation": object | undefined// present when referenceStyle is set — see In-text
}
DoiReport object
"total": number
"valid": number// DOI resolved and confirmed
"autofilled": number// DOI found by CrossRef or PubMed
"corrected": number// DOI was wrong, auto-corrected
"issues": number// couldn't resolve
"fieldsAdded": number// total fields filled (vol, issue, pages, authors)
"entries": DoiValidation[]// per-reference detail
}
Code Examples
BibTeX input example
curl -X POST https://your-domain.com/refright/api/parse \ -H "X-API-Key: rr_live_xxxx" \ -H "Content-Type: application/json" \ -d '{ "references": "@article{smith2022,\n author={Smith, John A and Jones, Karen B},\n title={mRNA vaccine efficacy},\n journal={N Engl J Med},\n year={2022},\n volume={387},\n pages={1302--1315}\n}", "sourceType": "bibtex", "referenceStyle": "vancouver", "format": "txt" }'
POST /api/lookup
Fetch full reference metadata from a single identifier. Supports DOI, PMID, ISBN, arXiv ID, and bioRxiv / medRxiv IDs. Returns a structured CSL-JSON object ready to convert.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| type | string | Required | Identifier type: doi · pmid · isbn · arxiv · biorxiv |
| id | string | Required | The identifier value. E.g. 10.1056/NEJMoa2209521 for DOI, 2303.08774 for arXiv, 33999615 for PMID. |
// DOI lookup { "type": "doi", "id": "10.1056/NEJMoa2209521" } // PubMed ID { "type": "pmid", "id": "33999615" } // ISBN (book) { "type": "isbn", "id": "9780134685991" } // arXiv preprint { "type": "arxiv", "id": "2303.08774" } // bioRxiv / medRxiv { "type": "biorxiv", "id": "10.1101/2021.01.08.425894" }
The lookup response is a raw CSL-JSON object. Pass the returned raw field as the references body to /api/parse to convert it into any citation style.
POST /api/retraction-check
Check a list of DOIs against CrossRef's live retraction, correction, and expression-of-concern database. Returns a status for each DOI — ok, retracted, concern, correction, or unknown.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| dois | string[] | Required | Array of DOI strings to check. E.g. ["10.1016/S0140-6736(97)11096-0", "10.1056/NEJMoa2209521"] |
response = requests.post(
f"{BASE_URL}/api/retraction-check",
headers={"X-API-Key": API_KEY},
json={
"dois": [
"10.1016/S0140-6736(97)11096-0", # Wakefield MMR paper — RETRACTED
"10.1038/s41586-021-03819-2", # AlphaFold — OK
]
}
)
results = response.json()["results"]
for r in results:
print(r["doi"], r["status"], r.get("noticeUrl"))
Response
"results": [
{
"doi": string
"status": "ok" | "retracted" | "concern" | "correction" | "unknown"
"noticeTitle": string | undefined// title of retraction notice
"noticeUrl": string | undefined// https://doi.org/… link to official notice
"noticeYear": number | undefined
}
]
}
GET /api/styles
Returns all available citation styles — built-in and any custom styles created in your account. Use the id field as the referenceStyle value in /api/parse.
{
"styles": [
{
"id": "apa7",
"name": "APA 7th Edition",
"builtIn": true,
"description": "American Psychological Association, 7th ed.",
"casing": {
"titleCase": "sentence",
"journalAbbrev":"as-is"
}
},
// … 7 more built-in styles + any custom styles
]
}
Output Formats
Pass as the format field in /api/parse.
| Value | Description | Styled? |
|---|---|---|
| json | Structured CSL-JSON — one object per reference with all parsed fields | ✓ |
| jats | JATS XML — journal publishing standard for submission systems | ✓ |
| bits | BITS XML — book interchange tag suite | ✓ |
| bib | BibTeX — for LaTeX workflows (\bibliography{}) | — |
| ris | RIS — import into Mendeley, Zotero, EndNote | — |
| csl | CSL-JSON — Citation Style Language structured format | — |
| xml | Generic XML — structured output with styled formatted field | ✓ |
| ref | REF format — plain structured reference format | — |
| txt | Plain text — one formatted citation per entry, newline separated | ✓ |
| html | Styled HTML — italic journal names, bold, ready to embed | ✓ |
| docx | Word Document — hanging indents, correct formatting, submission-ready | ✓ |
| PDF — Times Roman, hanging indents, publication-ready | ✓ |
Styled? = format supports styled output when a referenceStyle is provided. Formats marked — return raw parsed data regardless of style setting.
Citation Style IDs
Custom styles created in the Style Manager are available by their slug. Retrieve the full list via GET /api/styles.
In-text Citation Format
When referenceStyle is set, every entry in parsedData includes an inTextCitation object with the correct form for that style.
| Style | inTextCitation object | Example |
|---|---|---|
| apa7 · harvard | { "authorYear": "..." } |
(Smith & Jones, 2022) |
| chicago | { "footnote": "1", "authorYear": "..." } |
footnote: 1 · (Smith and Jones, 2022) |
| chicago-author-date | { "authorYear": "..." } |
(Smith and Jones, 2022) |
| mla9 | { "authorPage": "..." } |
(Smith 1302) |
| ieee · vancouver · ama | { "numeric": "[N]", "superscript": "N" } |
[1] or superscript 1 |
SDKs & Libraries
Official SDKs are coming soon. For now, the API is a plain REST interface — any HTTP client works. The examples above cover cURL, Python (requests), Node.js (fetch), and PHP (curl). Community SDKs are welcome — open a PR or reach out at support@refright.io.
Need help? Email support@refright.io or open the workspace and use the live demo to test your references before integrating.