Citations API

The Citations API allows you to track, manage, and verify the sources of information used by Oliver in its responses. This feature is especially crucial for financial firms that must maintain regulatory compliance and provide traceable sources for information.

Best Practice: Our system automatically generates citations for information sourced from web browsing, RAG documents, and other sources. You can use this API to retrieve detailed information about these citations.

Citation Object

The Citation object represents a reference to a source of information used in an AI response.

Attribute	Type	Description
id	string	Unique identifier for the citation
message_id	string	ID of the message that contains this citation
source_type	string	Type of source (web_page, rag_document, search_result, etc.)
source_id	string	ID of the source object (corresponding to source_type)
title	string	Title of the source
url	string	URL of the source (if applicable)
snippet	string	A snippet of the referenced content
metadata	object	Additional metadata about the source
created_at	timestamp	When the citation was created

Get Message Citations

Retrieve all citations for a specific message.

Endpoint

GET https://api.oliverchat.com/v1/citations/message/{message_id}

Example Response

{
  "success": true,
  "data": [
    {
      "id": "citation_123456789",
      "message_id": "msg_987654321",
      "source_type": "web_page",
      "source_id": "webpage_123456789",
      "title": "Market Update: Q1 2025 Financial Outlook",
      "url": "https://www.example.com/financial-news/article",
      "snippet": "The financial markets experienced significant growth in Q1 2025, with major indices rising by an average of 8.3%.",
      "metadata": {
        "author": "Jane Smith",
        "published_date": "2025-03-10T08:30:00Z",
        "publisher": "Financial News Today"
      },
      "created_at": "2025-03-11T10:20:00Z"
    },
    {
      "id": "citation_123456790",
      "message_id": "msg_987654321",
      "source_type": "rag_document",
      "source_id": "doc_123456789",
      "title": "Investment Strategy Guide 2025",
      "url": "https://ragcontainer.oliverchat.com/docs/investment-strategy-2025.pdf",
      "snippet": "For moderate risk tolerance investors, a balanced portfolio with 60% equities, 30% fixed income, and 10% alternatives is generally recommended.",
      "metadata": {
        "author": "Advisors Asset Management",
        "published_date": "2025-01-15T00:00:00Z",
        "document_type": "PDF"
      },
      "created_at": "2025-03-11T10:20:00Z"
    }
  ],
  "message": "Citations retrieved successfully"
}

Get Citation Details

Retrieve detailed information about a specific citation.

Endpoint

GET https://api.oliverchat.com/v1/citations/{citation_id}

Example Response

{
  "success": true,
  "data": {
    "id": "citation_123456789",
    "message_id": "msg_987654321",
    "source_type": "web_page",
    "source_id": "webpage_123456789",
    "title": "Market Update: Q1 2025 Financial Outlook",
    "url": "https://www.example.com/financial-news/article",
    "snippet": "The financial markets experienced significant growth in Q1 2025, with major indices rising by an average of 8.3%.",
    "metadata": {
      "author": "Jane Smith",
      "published_date": "2025-03-10T08:30:00Z",
      "publisher": "Financial News Today",
      "section": "Market Analysis",
      "tags": ["markets", "financial outlook", "investments", "2025 forecast"]
    },
    "created_at": "2025-03-11T10:20:00Z",
    "source_content": {
      "id": "webpage_123456789",
      "url": "https://www.example.com/financial-news/article",
      "title": "Market Update: Q1 2025 Financial Outlook",
      "content_snippet": "The financial markets experienced significant growth in Q1 2025, with major indices rising by an average of 8.3%. Analysts attribute this growth to several factors including favorable monetary policy decisions...",
      "mime_type": "text/html",
      "created_at": "2025-03-11T10:15:05Z"
    }
  },
  "message": "Citation details retrieved successfully"
}

Get Chat Citations

Retrieve all citations used in a specific chat.

Endpoint

GET https://api.oliverchat.com/v1/citations/chat/{chat_id}

Query Parameters

limit: Maximum number of citations to return (default: 20, max: 100)
offset: Offset for pagination (default: 0)
source_type: Filter by source type (optional)
sort: Sort by field (default: "created_at", options: "created_at", "source_type", "title")
order: Sort order (default: "desc", options: "asc")

Example Response

{
  "success": true,
  "data": [
    {
      "id": "citation_123456789",
      "message_id": "msg_987654321",
      "source_type": "web_page",
      "source_id": "webpage_123456789",
      "title": "Market Update: Q1 2025 Financial Outlook",
      "url": "https://www.example.com/financial-news/article",
      "snippet": "The financial markets experienced significant growth in Q1 2025, with major indices rising by an average of 8.3%.",
      "metadata": {
        "author": "Jane Smith",
        "published_date": "2025-03-10T08:30:00Z",
        "publisher": "Financial News Today"
      },
      "created_at": "2025-03-11T10:20:00Z"
    },
    {
      "id": "citation_123456790",
      "message_id": "msg_987654321",
      "source_type": "rag_document",
      "source_id": "doc_123456789",
      "title": "Investment Strategy Guide 2025",
      "url": "https://ragcontainer.oliverchat.com/docs/investment-strategy-2025.pdf",
      "snippet": "For moderate risk tolerance investors, a balanced portfolio with 60% equities, 30% fixed income, and 10% alternatives is generally recommended.",
      "metadata": {
        "author": "Advisors Asset Management",
        "published_date": "2025-01-15T00:00:00Z",
        "document_type": "PDF"
      },
      "created_at": "2025-03-11T10:20:00Z"
    }
  ],
  "meta": {
    "total": 2,
    "per_page": 20,
    "page": 1,
    "total_pages": 1
  },
  "message": "Citations retrieved successfully"
}

Citation Source Types

Oliver Chat supports various types of citation sources:

Source Type	Description
web_page	Content from a browsed web page
rag_document	Content from a document in a RAG container
search_result	Content from a search result via the Search API
uploaded_file	Content from a file uploaded during the chat
financial_database	Content from an integrated financial database

Get Citation Source Content

Retrieve the full content of a citation source.

Endpoint

GET https://api.oliverchat.com/v1/citations/{citation_id}/source-content

Example Response (for a web_page source)

{
  "success": true,
  "data": {
    "id": "webpage_123456789",
    "browse_session_id": "browse_123456789",
    "url": "https://www.example.com/financial-news/article",
    "title": "Market Update: Q1 2025 Financial Outlook",
    "content": "The financial markets experienced significant growth in Q1 2025, with major indices rising by an average of 8.3%. Analysts attribute this growth to several factors including favorable monetary policy decisions, strong corporate earnings reports, and increased investor confidence.\n\nThe technology sector led the gains with a 12.1% increase, followed by healthcare at 9.7% and financials at 7.8%. Small-cap stocks also performed well, with the Russell 2000 index gaining 10.2% during the quarter.\n\nAnalysts from major investment banks are cautiously optimistic about the remainder of the year, citing potential headwinds from inflation and supply chain constraints that could impact growth in the second half of 2025.",
    "mime_type": "text/html",
    "metadata": {
      "author": "Jane Smith",
      "published_date": "2025-03-10T08:30:00Z",
      "publisher": "Financial News Today",
      "section": "Market Analysis",
      "tags": ["markets", "financial outlook", "investments", "2025 forecast"]
    },
    "created_at": "2025-03-11T10:15:05Z"
  },
  "message": "Source content retrieved successfully"
}

Compliance Considerations

Financial Services Compliance

When using the Citations API in financial contexts, consider the following compliance requirements:

All financial advice must be properly attributed to its source
Citations should be retained according to your firm's data retention policies
Verify that cited sources meet your organization's credibility standards
Implement additional compliance checks for citations used in client-facing materials
Ensure citations from regulatory sources are accurately referenced

Implementing Citations in Your UI

To display citations effectively in your user interface:

Retrieve citations for each message using the API
Display citation indicators next to relevant portions of AI responses
Allow users to click on citations to view source details
Provide a way to export or download citation information for record-keeping

Here's a sample JavaScript implementation for retrieving and displaying citations:

// Get citations for a message
async function getCitations(messageId) {
  const response = await fetch(`https://api.oliverchat.com/v1/citations/message/${messageId}`, {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Accept': 'application/json'
    }
  });
  
  const data = await response.json();
  
  if (data.success) {
    return data.data;
  } else {
    console.error('Error fetching citations:', data.error);
    return [];
  }
}

// Display citations in UI
function displayCitations(messageElement, citations) {
  const citationsContainer = document.createElement('div');
  citationsContainer.className = 'citations-container mt-2 border-t border-gray-200 pt-2';
  
  if (citations.length === 0) {
    return;
  }
  
  const citationsList = document.createElement('ul');
  citationsList.className = 'citations-list text-sm text-gray-600';
  
  citations.forEach((citation, index) => {
    const citationItem = document.createElement('li');
    citationItem.className = 'citation-item mb-1';
    
    const sourceLink = document.createElement('a');
    sourceLink.href = citation.url || '#';
    sourceLink.target = '_blank';
    sourceLink.className = 'font-medium text-blue-600 hover:underline';
    sourceLink.textContent = `[${index + 1}] ${citation.title}`;
    
    citationItem.appendChild(sourceLink);
    
    // Add metadata if available
    if (citation.metadata && citation.metadata.author) {
      const metadata = document.createElement('span');
      metadata.className = 'ml-2 text-gray-500';
      metadata.textContent = `by ${citation.metadata.author}`;
      citationItem.appendChild(metadata);
    }
    
    citationsList.appendChild(citationItem);
  });
  
  citationsContainer.appendChild(citationsList);
  messageElement.appendChild(citationsContainer);
}

Error Responses

Citation Not Found

{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "Citation not found",
    "details": null
  }
}

Source Content Not Available

{
  "success": false,
  "error": {
    "code": "content_unavailable",
    "message": "Source content is no longer available",
    "details": {
      "reason": "Content has been removed or expired"
    }
  }
}

Next: Financial Compliance API Back to Browsing API

Citations API

Citation Object

Get Message Citations

Endpoint

Example Response

Get Citation Details

Endpoint

Example Response

Get Chat Citations

Endpoint

Query Parameters

Example Response

Citation Source Types

Get Citation Source Content

Endpoint

Example Response (for a web_page source)

Compliance Considerations

Financial Services Compliance

Implementing Citations in Your UI

Error Responses

Citation Not Found

Source Content Not Available

Test the Citations API