Developer Portal

Dimensions Citation Check API

Upload academic PDFs to detect and assess self-citation patterns, returning quantitative metrics and optional AI-driven qualitative evaluations.

Last update June 30, 2026

The Dimensions Citation Check API lets you upload academic PDF manuscripts and receive a structured analysis of self-citation patterns. It identifies self-citations, calculates quantitative metrics, and can run an AI-based qualitative assessment of the appropriateness of those citations.

Responses are returned as JSON, and the API uses standard HTTP status codes to indicate success and failure. A base64-encoded HTML report can be included for direct embedding in web applications.

  1. Base URL: https://api.digital-science.com/citation-check/v2
  2. Authentication: Include your API key in the X-API-KEY header.
  3. Format: Requests use multipart/form-data for uploads; responses are JSON.
⏱️

Processing time depends on PDF size, analysis depth, and mode. For large PDFs or full AI analysis, use a client timeout of at least 300 seconds. The service supports up to 10 simultaneous requests.

Endpoints

  • Headers
    • X-API-KEY: Your API key (required)
    • Content-Type: multipart/form-data (required for file upload)

Analyze a Manuscript

Endpoint

POST /citation-check/v2/analyze

Description

Upload a single PDF to extract self-citation metrics and, optionally, run an AI-driven qualitative assessment. The response includes document metadata and metrics, and can optionally include a base64-encoded HTML report, detailed references, and a full structured analysis for custom UI rendering.

Request

  • Query Parameters:

    • run_ai_analysis (boolean, optional, default: true): If true, runs the LLM-based qualitative assessment; if false, returns only quantitative metrics.
    • include_html (boolean, optional, default: true): If true, includes a base64-encoded HTML report in report.
    • include_references (boolean, optional, default: false): If true, includes document.references and document.resolved_references.
    • include_details (boolean, optional, default: false): If true, includes a details object with the full structured analysis (per-author summary, editorial assessment, sentence contexts, and individual AI evaluations).
    • mode (enum, optional, default: default): LLM mode profile. One of: default, fast, accurate.

  • Body (multipart/form-data):

    • file (file, required): The PDF to analyze. Must be a valid .pdf file.
copy
curl -X POST "https://api.digital-science.com/citation-check/v2/analyze?run_ai_analysis=true&include_html=true&include_references=false&include_details=true&mode=default" \
  -H "X-API-KEY: {YOUR_API_KEY}" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@/path/to/manuscript.pdf;type=application/pdf"

Version behavior

  • This v2 endpoint always uses the LLM engine and does not fall back to legacy processing.
  • The engine query parameter is not supported in v2 and will be rejected.

Response

  • 200 OK
    • Body (JSON): 
      {
  "document": {
    "metadata": {
      "title": "Example Title",
      "authors": ["Author A", "Author B"]
    },
    "filename": "paper.pdf",
    "references": [],
    "resolved_references": []
  },
  "metrics": {
    "total_authors": 4,
    "total_references": 43,
    "total_self_citation_sentences": 7,
    "pct_self_citation": 39.5,
    "editorial_risk": "high",
    "ai_quality_assessment": {
      "appropriate": 4,
      "questionable": 2,
      "inappropriate": 1
    }
  },
  "report": "PCFET0NUWVBFIGh0bWw+..."
}
    • Key behaviors and optional fields:
      • report is null when include_html=false.
      • document.references and document.resolved_references are only present when include_references=true.
      • details is only present when include_details=true (see below).
      • ai_quality_assessment is always present with integer counts (zeros if no AI analysis ran or no self-citations were found).
details object (when include_details=true)
{
  "details": {
    "risk_help": "High Risk: 1 inappropriate citation(s) found",
    "overall_assessment": {
      "risk_level": "high",
      "editorial_recommendation": "...",
      "reasoning": "...",
      "actions": ["..."]
    },
    "summary": [
      {
        "Author": "Smith, J",
        "References Count": 3,
        "References %": 7.0,
        "In-Text Citations": 5,
        "In-Text %": 12.5
      }
    ],
    "self_citation_sentences": [
      {
        "section": "Introduction",
        "paragraph": "...",
        "sentence_idx": 2,
        "sentence": "As shown in [Smith, 2020] ...",
        "self_citations": [
          {
            "citation_match_id": "...",
            "citation_text": "[Smith, 2020]",
            "citation": { "text": "[Smith, 2020]", "ref_id": "b12" },
            "reference": { "id": "b12", "title": "...", "year": "2020" },
            "matching_authors": ["Smith, J"]
          }
        ]
      }
    ],
    "individual_evaluations": [
      {
        "citation_match_id": "...",
        "citation": "[Smith, 2020]",
        "section": "Introduction",
        "sentence": "As shown in [Smith, 2020] ...",
        "reference_title": "...",
        "evaluation": {
          "level": "appropriate",
          "reasoning": "...",
          "confidence": 0.92,
          "red_flags": []
        }
      }
    ]
  }
}
  • Field notes:
    • overall_assessment is null when run_ai_analysis=false or no self-citations were found.
    • summary aggregates per-author self-citation activity.
    • self_citation_sentences provides sentence-level contexts and matched citations.
    • individual_evaluations provides AI labels per citation instance.

Error Handling

If an error occurs, the API returns an appropriate HTTP status and an error body of the form:

{
  "error": {
    "code": "PDF_1003",
    "message": "Invalid file format",
    "details": "File must be a PDF. Only .pdf extension is accepted."
  }
}
  • 400 Bad Request: Invalid input (e.g., not a PDF, corrupted, or empty file).
  • 401 Unauthorized: Missing X-API-KEY header.
  • 403 Forbidden: Invalid API key.
  • 422 Unprocessable Entity: Content could not be processed (e.g., no text extracted, no authors or references found, XML parsing error).
  • 500 Internal Server Error: Unexpected server-side error.
  • 503 Service Unavailable: A required dependency is unavailable.
  • 504 Gateway Timeout: Processing exceeded time limits (e.g., extraction service timeout).

Limitations and Best Practices

  • Performance:
    • Larger PDFs and more pages increase processing time.
    • run_ai_analysis=true adds LLM processing per detected self-citation.
    • mode selection (default, fast, accurate) impacts runtime and cost/quality balance.
  • Timeouts: Use a client timeout of at least 300 seconds for large PDFs or full AI analysis.

Reasonable Use

The purpose of the API is to help users include Dimensions citation checks as part of their internal manuscript review workflows.

The API is provided strictly for your own internal use. This means that any app which makes use of the API must be strictly access controlled, with access limited to your staff. Use in connection with apps that are accessible outside of your organization or used to provide services to others is strictly prohibited. Use in connection with apps that you do not own or control is not permitted without specific prior written approval.

Your subscription to use the API may include a defined number of API keys. Any key generated in excess of that number may be revoked without notice, or subject to additional charges. Use of a key must be limited to a specific internal application i.e. a specific software application, tool or dashboard owned or controlled by you, accessible only to your staff, with a single, clearly defined use case (we define “use case” as a consistent set of analyses, displays, or actions). Access credentials should not be used across multiple apps.

If access is authorized via MCP, this is allowed at our discretion for convenience only, use restrictions and limitations must still be fully respected (never by-passed or circumvented), and you must not make use of the API in a manner that (in our absolute discretion) exceeds reasonable usage patterns. Without limiting that discretion, we may determine unreasonable usage by comparing your activity for any given period against the average of other users not making use of an MCP.

You should limit your use to what is necessary for the review(s) you are performing, not to support non-specific tasks or benchmark Dimensions Citation Check, and never in a way which may have an adverse impact on the performance or others’ use of the API. Uses for training purposes are not permitted.

We reserve the right to impose such limits on the API as we consider are reasonable. Any account associated with a violation of these rules may be subject to enforcement action, including suspension. Please also make sure you comply with the other terms of your Dimensions subscription.

Technical Limits

Each API key has a concurrency limit that should not be exceeded.

The API is meant for processing scientific manuscripts. Manuscripts that exceed the typical size of a scientific publication (e.g., entire books) will be rejected by the API.

    Dimensions Citation Check API : API Reference - Developer Portal