Getting Started

Learn how to install and integrate DeepCitation into your application.

How DeepCitation Works

DeepCitation works in 3 sections: install & setup, server side, and display.

Section 1: Install & Setup

Install, import types, initialize client, prepare sources, and configure proof images.

Section 2: Server Side

Wrap prompts, call your LLM, verify citations, and optionally persist results.

Section 3: Display with CitationComponent

Parse numeric [N] markers via parseCitationResponse, map to citation keys, and render inline with verification status.

Installation

Install the SDK using your preferred package manager:

# npm
npm install deepcitation

# yarn
yarn add deepcitation

# pnpm
pnpm add deepcitation

# bun
bun add deepcitation

Full Integration Example

import { DeepCitation, wrapCitationPrompt, getAllCitationsFromLlmOutput } from "deepcitation";

const dc = new DeepCitation({ apiKey: process.env.DEEPCITATION_API_KEY });

// 1. Prepare your source document
const { fileDataParts, deepTextPromptPortion } = await dc.prepareAttachments([
  { file: pdfBuffer, filename: "report.pdf" },
]);
const attachmentId = fileDataParts[0].attachmentId;

// 2. Wrap your prompts with citation instructions
const systemPrompt = "You are a helpful assistant that cites sources.";

const { enhancedSystemPrompt, enhancedUserPrompt } = wrapCitationPrompt({
  systemPrompt,
  userPrompt,
  deepTextPromptPortion,
});

// 3. Call your LLM
const response = await yourLLM.chat({
  messages: [
    { role: "system", content: enhancedSystemPrompt },
    { role: "user", content: enhancedUserPrompt },
  ],
});

// 4. Extract and verify citations
const citations = getAllCitationsFromLlmOutput(response.content);
const { verifications } = await dc.verifyAttachment(attachmentId, citations);

// 5. Use verification results
for (const [key, result] of Object.entries(verifications)) {
  console.log(`Citation ${key}: ${result.searchState?.status}`);
  if (result.verificationImageBase64) {
    // Display visual proof to users
  }
}

Section 3: Render (React)

import { parseCitationResponse } from "deepcitation";
import { CitationComponent } from "deepcitation/react";

const { visibleText, citations, markerMap, splitPattern } = parseCitationResponse(llmOutput);

return (
  <p>
    {visibleText.split(splitPattern).map((part, i) => {
      const key = markerMap[Number(part.replace(/[\[\]]/g, ""))];
      if (key) {
        return (
          <CitationComponent
            key={`${key}-${i}`}
            citation={citations[key]}
            verification={verifications[key]}
          />
        );
      }
      return <span key={i}>{part}</span>;
    })}
  </p>
);

Authentication

Include your API key in the Authorization header:

Authorization: Bearer dc_live_your_api_key

Get your API key from the API Keys Page.

Base URL

All API endpoints are available at:

https://api.deepcitation.com

The SDK handles API routing automatically. You only need to configure your API key.

Supported File Types

Type	Formats
PDFs	`.pdf`
Images	`.jpg`, `.jpeg`, `.png`, `.gif`, `.webp` (auto-OCR)
Office Docs	Word, Excel, PowerPoint, Google Docs
URLs	Web pages via `prepareUrl` endpoint

Next Steps

API Reference - Learn about the REST API endpoints
Components - Display citations with React components
Code Examples - See more integration patterns
Error Handling - Production error patterns and retry logic
Styling - CSS customization and theming