Citations

What Are Citations?

Citations in Quantly are inline references that connect AI-generated responses to their original source materials. When the AI provides information, it includes citations to help you verify the information and explore the source documents.

Why Citations Matter

Transparency: See exactly where information comes from
Verification: Check the AI’s analysis against source materials
Navigation: Access specific document sections directly
Trust: Build confidence in AI-generated insights
Compliance: Meet regulatory requirements for sourced information

Citation Format

Citations follow a standardized bracket notation:

[SourceType:SourceId:ChunkId]

Format Components

[SourceType:SourceId:ChunkId]

Component

Description

Required

Example

SourceType

The type of document being referenced

✅ Yes

Transcript, Filing, UserDocument, Internet

SourceId

Unique identifier for the specific document

✅ Yes

12345 (integer), 550e8400-... (UUID)

ChunkId

Specific section within the document

⚠️ Optional

42

Citation Patterns

Full Citation (with chunk):

[Transcript:12345:42]

References transcript #12345, chunk #42

Document-Level Citation (without chunk):

[Filing:98765]

References filing #98765 without specifying a particular section

Citation Types

Quantly supports four types of source citations:

1. Transcript Citations

Format:

[Transcript:TranscriptId:ChunkId]

References earnings call transcripts and other company presentations.

ID Format: Integer

Examples:

[Transcript:54321:10] - Transcript #54321, chunk 10
[Transcript:98765] - Transcript #98765 (entire document)

Use Cases:

Earnings call analysis
Management commentary
Q&A session insights
Forward-looking statements

2. Filing Citations

Format:

[Filing:FilingId:ChunkId]

References SEC filings (10-K, 10-Q, 8-K, etc.) and other regulatory documents.

ID Format: Integer

Examples:

[Filing:41234:150] - Filing #41234, chunk 150
[Filing:6453] - Filing #6453 (entire document)

Use Cases:

Financial statement analysis
Risk factor assessment
Business description review
Legal proceedings research

3. SlideDeck Citations

Format:

[SlideDeck:SlideDeckId:ChunkId]

References investor presentation slides and pitch decks.

ID Format: Integer

Examples:

[SlideDeck:67890:5] - Slide deck #67890, chunk 5
[SlideDeck:11223] - Slide deck #11223 (entire document)

Use Cases:

Strategy overview
Product roadmap analysis
Market positioning
Growth projections

4. UserDocument Citations

Format:

[UserDocument:DocumentId:ChunkId]

References documents uploaded by users to the system.

ID Format: UUID (GUID)

Examples:

[UserDocument:550e8400-e29b-41d4-a716-446655440000:7] - User document with chunk 7
[UserDocument:7c9e6679-7425-40de-944b-e07fc1f90ae7] - User document (entire document)

Use Cases:

Custom research papers
Internal reports
Third-party analysis
Proprietary documents

5. Internet Citations

Format:

[Internet:Guid]

References information from web searches performed by the AI.

ID Format: UUID (GUID)

Note: Internet citations do not support chunk IDs.

Examples:

[Internet:550e8400-e29b-41d4-a716-446655440000] - Web search result

Use Cases:

Market news
Industry trends
Public company information
External research

Retrieving Citation Data

Each citation type has a corresponding API endpoint to retrieve the source document and specific chunk data.

Authentication

All API endpoints require authentication via Bearer token:

Authorization: Bearer your_api_token

Transcript Citations

Endpoint:

GET /v1/transcripts/{transcriptId}/source?chunkId={chunkId}

Parameters:

transcriptId (path, required): Integer ID of the transcript
chunkId (query, optional): Integer ID of the specific chunk

Example:

GET /v1/transcripts/12345/source?chunkId=42

Response Fields:

id: Transcript ID
title: Transcript title
date: Transcript date
companyId: Associated company ID
chunkId: Chunk ID (if requested)
content: Chunk text content (if chunk ID provided)

Without Chunk ID:

GET /v1/transcripts/12345/source

Returns transcript metadata without specific chunk content.

Filing Citations

Endpoint:

GET /v1/filings/{filingId}/source?chunkId={chunkId}

Parameters:

filingId (path, required): Integer ID of the filing
chunkId (query, optional): Integer ID of the specific chunk

Example:

GET /v1/filings/41234/source?chunkId=150

Response Fields:

id: Filing ID
title: Filing title (e.g., “10-K”, “10-Q”)
date: Filing date
companyId: Associated company ID
chunkId: Chunk ID (if requested)
content: Chunk text content (if chunk ID provided)
pageNumber: Page number where chunk is located (if available)
boundingBox: Coordinates of text location on page (if available)

Additional Endpoints:

Get Pre-signed URL for PDF Download:

GET /v1/filings/{filingId}/presignedUrl

Returns a temporary URL for downloading the original filing PDF.

SlideDeck Citations

Endpoint:

GET /v1/slidedecks/{slideDeckId}/source?chunkId={chunkId}

Parameters:

slideDeckId (path, required): Integer ID of the slide deck
chunkId (query, optional): Integer ID of the specific chunk

Example:

GET /v1/slidedecks/67890/source?chunkId=5

Response Fields:

id: Slide deck ID
title: Presentation title
date: Presentation date
companyId: Associated company ID
chunkId: Chunk ID (if requested)
content: Chunk text content (if chunk ID provided)
pageNumber: Slide/page number where chunk is located
boundingBox: Coordinates of text location on slide (if available)

Additional Endpoints:

Get Pre-signed URL for PDF Download:

GET /v1/slidedecks/{slideDeckId}/presignedUrl

Returns a temporary URL for downloading the original presentation PDF.

UserDocument Citations

Endpoint:

GET /v1/documents/{documentId}/source?chunkId={chunkId}

Parameters:

documentId (path, required): UUID of the uploaded document
chunkId (query, optional): Integer ID of the specific chunk

Example:

GET /v1/documents/550e8400-e29b-41d4-a716-446655440000/source?chunkId=7

Response Fields:

id: Document UUID
title: Document title
fileType: Document file type (e.g., “pdf”, “docx”)
chunkId: Chunk ID (if requested)
content: Chunk text content (if chunk ID provided)
pageNumber: Page number where chunk is located (for PDFs)
boundingBox: Coordinates of text location on page (for PDFs)

Additional Endpoints:

Get Full Document Metadata:

GET /v1/documents/{documentId}

Get Full Document Content:

GET /v1/documents/{documentId}/content

Get Pre-signed URL for Download:

GET /v1/documents/{documentId}/preSignedUrl

Internet Citations

Endpoint:

GET /v1/chats/{chatId}/webResults/{webResultId}

Parameters:

chatId (path, required): UUID of the chat containing the web result
webResultId (path, required): UUID of the web search result (the GUID from the citation)

Example:

GET /v1/chats/a1b2c3d4-e5f6-7890-abcd-ef1234567890/webResults/550e8400-e29b-41d4-a716-446655440000

Response Fields:

id: Web result UUID
url: URL of the source webpage
title: Title of the webpage
date: Date when the source was published (if available)

Note: Internet citations do not have chunk IDs. The citation format is [Internet:Guid] only.

Getting Multiple Web Results:

GET /v1/chats/{chatId}/webResults?ids={id1}&ids={id2}&ids={id3}

Error Responses

All endpoints may return the following error responses:

404 Not Found:

{
  "message": "Document not found",
  "statusCode": 404
}

The requested document or chunk does not exist.

401 Unauthorized:

{
  "message": "Unauthorized",
  "statusCode": 401
}

Authentication token is missing or invalid.

429 Too Many Requests:

{
  "message": "Rate limit exceeded",
  "statusCode": 429
}

Too many API requests in a short time period.

Working with Citations

Reading Citations in AI Responses

When you receive an AI response, citations appear inline:

Apple's gross margin improved to 45.2% [Transcript:12345:8] driven by
favorable product mix [Filing:98765:42] and operational efficiencies
[SlideDeck:67890:15].

Each citation tells you:

Source Type: What kind of document (Transcript, Filing, etc.)
Source ID: Which specific document
Chunk ID: Which section of the document (if specified)

Following Citations

To explore a citation:

Extract the citation components from the bracket notation
Call the appropriate API endpoint with the source ID
Add the chunk ID as a query parameter if you want specific chunk content
Review the returned data

Extracting Citations with Python

Here’s how to parse and extract citations from AI responses using Python:

import re
from typing import List, Dict, Optional
from dataclasses import dataclass

@dataclass
class Citation:
    """Represents a parsed citation."""
    source_type: str
    source_id: str
    chunk_id: Optional[str] = None

    def __str__(self) -> str:
        if self.chunk_id:
            return f"[{self.source_type}:{self.source_id}:{self.chunk_id}]"
        return f"[{self.source_type}:{self.source_id}]"

def extract_citations(text: str) -> List[Citation]:
    """
    Extract all citations from text.

    Args:
        text: Text containing citations in format [SourceType:SourceId:ChunkId]

    Returns:
        List of Citation objects
    """
    # Regex pattern matches: [SourceType:SourceId] or [SourceType:SourceId:ChunkId]
    pattern = r'\[([^\]:]+):([^\]:]+)(?::([^\]]+))?\]'

    citations = []
    for match in re.finditer(pattern, text):
        source_type = match.group(1)
        source_id = match.group(2)
        chunk_id = match.group(3) if match.group(3) else None

        citation = Citation(
            source_type=source_type,
            source_id=source_id,
            chunk_id=chunk_id
        )
        citations.append(citation)

    return citations

def get_unique_citations(citations: List[Citation]) -> List[Citation]:
    """Remove duplicate citations from a list."""
    seen = set()
    unique = []

    for citation in citations:
        key = (citation.source_type, citation.source_id, citation.chunk_id)
        if key not in seen:
            seen.add(key)
            unique.append(citation)

    return unique

# Example usage
text = """
Apple's revenue grew 15% [Transcript:12345:10] year-over-year,
driven by strong iPhone sales [Filing:98765:42] and services growth.
The company also highlighted expansion in emerging markets [Transcript:12345:28].
"""

citations = extract_citations(text)
unique_citations = get_unique_citations(citations)

for citation in unique_citations:
    print(f"Source: {citation.source_type}")
    print(f"ID: {citation.source_id}")
    print(f"Chunk: {citation.chunk_id}")
    print(f"Full: {citation}")
    print("---")

Output:

Source: Transcript
ID: 12345
Chunk: 10
Full: [Transcript:12345:10]
---
Source: Filing
ID: 98765
Chunk: 42
Full: [Filing:98765:42]
---
Source: Transcript
ID: 12345
Chunk: 28
Full: [Transcript:12345:28]
---

Fetching Citation Data with Python

Here’s how to retrieve the actual citation data using the API:

import requests
from typing import Optional, Dict, Any

class QuantlyAPI:
    """Client for Quantly API."""

    def __init__(self, api_key: str, base_url: str = "https://api.quantly.com"):
        self.api_key = api_key
        self.base_url = base_url
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        }

    def get_transcript_source(
        self,
        transcript_id: int,
        chunk_id: Optional[int] = None
    ) -> Dict[str, Any]:
        """Fetch transcript source data."""
        url = f"{self.base_url}/v1/transcripts/{transcript_id}/source"
        params = {"chunkId": chunk_id} if chunk_id else {}

        response = requests.get(url, headers=self.headers, params=params)
        response.raise_for_status()
        return response.json()

    def get_filing_source(
        self,
        filing_id: int,
        chunk_id: Optional[int] = None
    ) -> Dict[str, Any]:
        """Fetch filing source data."""
        url = f"{self.base_url}/v1/filings/{filing_id}/source"
        params = {"chunkId": chunk_id} if chunk_id else {}

        response = requests.get(url, headers=self.headers, params=params)
        response.raise_for_status()
        return response.json()

    def get_slidedeck_source(
        self,
        slidedeck_id: int,
        chunk_id: Optional[int] = None
    ) -> Dict[str, Any]:
        """Fetch slide deck source data."""
        url = f"{self.base_url}/v1/slidedecks/{slidedeck_id}/source"
        params = {"chunkId": chunk_id} if chunk_id else {}

        response = requests.get(url, headers=self.headers, params=params)
        response.raise_for_status()
        return response.json()

    def get_document_source(
        self,
        document_id: str,
        chunk_id: Optional[int] = None
    ) -> Dict[str, Any]:
        """Fetch user document source data."""
        url = f"{self.base_url}/v1/documents/{document_id}/source"
        params = {"chunkId": chunk_id} if chunk_id else {}

        response = requests.get(url, headers=self.headers, params=params)
        response.raise_for_status()
        return response.json()

    def get_web_result(
        self,
        chat_id: str,
        web_result_id: str
    ) -> Dict[str, Any]:
        """Fetch web search result citation."""
        url = f"{self.base_url}/v1/chats/{chat_id}/webResults/{web_result_id}"

        response = requests.get(url, headers=self.headers)
        response.raise_for_status()
        return response.json()

    def fetch_citation_data(
        self,
        citation: Citation,
        chat_id: Optional[str] = None
    ) -> Dict[str, Any]:
        """
        Fetch data for any citation type.

        Args:
            citation: Citation object with source type, ID, and optional chunk ID
            chat_id: Required for Internet citations only

        Returns:
            API response data
        """
        source_type = citation.source_type.lower()
        chunk_id = int(citation.chunk_id) if citation.chunk_id else None

        if source_type == "transcript":
            return self.get_transcript_source(int(citation.source_id), chunk_id)
        elif source_type == "filing":
            return self.get_filing_source(int(citation.source_id), chunk_id)
        elif source_type == "slidedeck":
            return self.get_slidedeck_source(int(citation.source_id), chunk_id)
        elif source_type == "userdocument":
            return self.get_document_source(citation.source_id, chunk_id)
        elif source_type == "internet":
            if not chat_id:
                raise ValueError("chat_id is required for Internet citations")
            return self.get_web_result(chat_id, citation.source_id)
        else:
            raise ValueError(f"Unknown citation type: {citation.source_type}")

# Example usage
api = QuantlyAPI(api_key="your_api_key_here")

# Parse citation from AI response
citation = Citation(
    source_type="Transcript",
    source_id="12345",
    chunk_id="42"
)

# Fetch the citation data
try:
    data = api.fetch_citation_data(citation)
    print(f"Title: {data['title']}")
    print(f"Content: {data.get('content', 'N/A')}")
    print(f"Chunk ID: {data.get('chunkId', 'N/A')}")
except requests.HTTPError as e:
    print(f"Error fetching citation: {e}")

Complete Example: Processing AI Response

Here’s a complete example that extracts citations from an AI response and fetches their data:

# AI response with citations
ai_response = """
Apple's Q4 2023 revenue reached $89.5B [Transcript:12345:15], representing
12% year-over-year growth. The growth was driven primarily by iPhone sales
[Filing:98765:78] and expanding services [SlideDeck:67890:22]. Management
highlighted particular strength in emerging markets [Transcript:12345:28]
and noted improving supply chain conditions.
"""

# Initialize API client
api = QuantlyAPI(api_key="your_api_key_here")

# Extract all citations
citations = extract_citations(ai_response)
unique_citations = get_unique_citations(citations)

print(f"Found {len(unique_citations)} unique citations\n")

# Fetch data for each citation
for i, citation in enumerate(unique_citations, 1):
    print(f"Citation {i}: {citation}")

    try:
        data = api.fetch_citation_data(citation)

        print(f"  Type: {citation.source_type}")
        print(f"  Document: {data.get('title', 'N/A')}")

        if citation.chunk_id:
            print(f"  Chunk {citation.chunk_id} content:")
            content = data.get('content', 'N/A')
            # Show first 100 characters
            print(f"    {content[:100]}...")

        print()

    except requests.HTTPError as e:
        print(f"  Error: {e}")
        print()

Summary

Citations in Quantly provide a transparent link between AI-generated insights and their source materials. By understanding:

Citation Format: [SourceType:SourceId:ChunkId]
Citation Types: Transcript, Filing, SlideDeck, UserDocument, Internet
API Endpoints: How to retrieve citation data programmatically
Python Integration: How to extract and fetch citation data

You can build applications that leverage Quantly’s sourced AI insights with full traceability and verification capabilities.