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.

HTTP Header
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

1
Sign up & get your API key
Create a free account at refright.io/signup and copy your API key from the Dashboard → API Keys section.
2
Add credits
Top up from ₹50. Plain parsing costs 1 credit/ref (₹0.10). Styled citations cost 3 credits/ref (₹0.30). Credits never expire.
3
Make your first call
POST a reference string to /api/parse with your key and chosen style. You'll get structured JSON + formatted output back in under a second.
cURL
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.

Plain parse (no style)
₹0.10 / ref
1 credit · Structured JSON, BibTeX, JATS XML, RIS
Styled citation
₹0.30 / ref
3 credits · Any of 8 styles + custom styles
Minimum top-up
₹50
= 500 credits · No expiry, no subscription
Max per request
100 refs
Batch up to 100 references in a single call

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.

PlanRequests / minMax refs / request
Pay As You Go60100
Starter60100
Pro120100
EnterpriseCustom100

Errors

RefRight uses standard HTTP status codes. Every error response is JSON with an error string field.

StatusMeaningCommon 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 Response
{
  "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.

POST /api/parse

Request Body

FieldTypeRequiredDescription
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

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 JA, Jones KB. mRNA vaccine efficacy against COVID-19 in sub-Saharan Africa. N Engl J Med. 2022;387(14):1302-1315. doi:10.1056/NEJMoa2209521\n\nHedgecock D, Pudovkin AI. Sweepstakes reproductive success in highly fecund marine fish. Bull Mar Sci. 2011;87(4):971-1002.",
    "referenceStyle": "apa7",
    "format": "txt",
    "lookupDoi": true,
    "fillMissing": true
  }'
import requests

API_KEY = "rr_live_xxxx"
BASE_URL = "https://your-domain.com/refright"

refs = """Smith JA, Jones KB. mRNA vaccine efficacy against COVID-19 in sub-Saharan Africa. N Engl J Med. 2022;387(14):1302-1315.

Hedgecock D, Pudovkin AI. Sweepstakes reproductive success in highly fecund marine fish. Bull Mar Sci. 2011;87(4):971-1002."""

response = requests.post(
    f"{BASE_URL}/api/parse",
    headers={"X-API-Key": API_KEY},
    json={
        "references":      refs,
        "referenceStyle":   "apa7",
        "format":           "txt",
        "lookupDoi":        True,
        "fillMissing":      True,
    }
)

data = response.json()
print(data["output"])          # formatted APA 7 text
print(data["doiReport"])       # DOI verification summary
print(data["creditsConsumed"])  # credits used

# In-text citations
for entry in data["parsedData"]:
    print(entry["inTextCitation"])  # e.g. {"authorYear": "(Smith & Jones, 2022)"}
const response = await fetch("https://your-domain.com/refright/api/parse", {
  method:  "POST",
  headers: {
    "X-API-Key":      "rr_live_xxxx",
    "Content-Type":   "application/json",
  },
  body: JSON.stringify({
    references:    "Smith JA, Jones KB. mRNA vaccines. N Engl J Med. 2022;387:1302.\n\nHedgecock D et al. Sweepstakes. Bull Mar Sci. 2011;87:971.",
    referenceStyle: "apa7",
    format:        "txt",
    lookupDoi:     true,
    fillMissing:   true,
  }),
});

const data = await response.json();
console.log(data.output);           // formatted APA 7 text
console.log(data.doiReport);        // { total, valid, corrected, autofilled, issues }
console.log(data.parsedData[0].inTextCitation); // { authorYear: "(Smith & Jones, 2022)" }
$ch = curl_init('https://your-domain.com/refright/api/parse');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'X-API-Key: rr_live_xxxx',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'references'     => 'Smith JA, Jones KB. mRNA vaccines. N Engl J Med. 2022;387:1302.',
        'referenceStyle' => 'apa7',
        'format'         => 'txt',
        'lookupDoi'      => true,
    ]),
]);
$body = curl_exec($ch);
$data = json_decode($body, true);
echo $data['output'];

BibTeX input example

cURL — BibTeX input
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.

POST /api/lookup

Request Body

FieldTypeRequiredDescription
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.
Examples
// 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.

POST /api/retraction-check

Request Body

FieldTypeRequiredDescription
dois string[] Required Array of DOI strings to check. E.g. ["10.1016/S0140-6736(97)11096-0", "10.1056/NEJMoa2209521"]
Python
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.

GET /api/styles
Response (truncated)
{
  "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.

ValueDescriptionStyled?
jsonStructured CSL-JSON — one object per reference with all parsed fields
jatsJATS XML — journal publishing standard for submission systems
bitsBITS XML — book interchange tag suite
bibBibTeX — for LaTeX workflows (\bibliography{})
risRIS — import into Mendeley, Zotero, EndNote
cslCSL-JSON — Citation Style Language structured format
xmlGeneric XML — structured output with styled formatted field
refREF format — plain structured reference format
txtPlain text — one formatted citation per entry, newline separated
htmlStyled HTML — italic journal names, bold, ready to embed
docxWord Document — hanging indents, correct formatting, submission-ready
pdfPDF — 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

apa7 mla9 chicago chicago-author-date harvard ieee vancouver ama your-custom-style-id

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.

StyleinTextCitation objectExample
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.