Developer Guide: Leveraging Citations & Enrichment

const API_KEY = 'YOUR_API_KEY';
const API_BASE = 'https://api.getmint.ai/api';

/**
 * Fetch all citations for a domain, paginating automatically.
 */
async function fetchAllCitations(domainId, filters = {}) {
  const citations = [];
  let page = 1;
  let hasNext = true;

  while (hasNext) {
    const params = new URLSearchParams({
      page: String(page),
      limit: '100',
      ...filters,
    });

    const res = await fetch(
      `${API_BASE}/domains/${domainId}/explorer/citations?${params}`,
      { headers: { 'X-API-Key': API_KEY } }
    );
    const data = await res.json();

    citations.push(...data.data);
    hasNext = data.hasNext;
    page++;
  }

  return citations;
}

/**
 * Enrich a batch of URLs with category + brand mention data.
 * Automatically chunks into batches of 100.
 */
async function enrichUrls(domainId, urls, reportId, topicId) {
  const enrichment = {};

  for (let i = 0; i < urls.length; i += 100) {
    const batch = urls.slice(i, i + 100);
    const res = await fetch(
      `${API_BASE}/domains/${domainId}/sources/enrichment`,
      {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'X-API-Key': API_KEY,
        },
        body: JSON.stringify({ urls: batch, reportId, topicId }),
      }
    );
    Object.assign(enrichment, await res.json());
  }

  return enrichment;
}

/**
 * Combined: fetch citations + enrich their sources.
 */
async function getCitationsWithEnrichment(domainId, reportId) {
  // 1. Fetch citations
  const citations = await fetchAllCitations(domainId, { latestOnly: 'true' });

  // 2. Collect unique URLs
  const urls = [...new Set(
    citations.map((c) => c.link).filter(Boolean)
  )];

  // 3. Enrich
  const enrichment = await enrichUrls(domainId, urls, reportId);

  // 4. Merge
  return citations.map((citation) => ({
    ...citation,
    enrichment: citation.link ? enrichment[citation.link] : undefined,
  }));
}

// Usage
const results = await getCitationsWithEnrichment('your-domain-id', 'your-report-id');

for (const row of results) {
  console.log(`[${row.promptCategory}] ${row.source}`);
  if (row.enrichment?.sourceCategory) {
    console.log(`  Category: ${row.enrichment.sourceCategory}`);
  }
  if (row.enrichment?.detectedBrands) {
    for (const brand of row.enrichment.detectedBrands) {
      const label = brand.isBrand ? 'own' : 'competitor';
      console.log(`  Brand: ${brand.name} (${label}, ${brand.count} mentions)`);
    }
  }
}

import requests

API_KEY = 'YOUR_API_KEY'
API_BASE = 'https://api.getmint.ai/api'
HEADERS = {'Content-Type': 'application/json', 'X-API-Key': API_KEY}


def fetch_all_citations(domain_id: str, filters: dict = None) -> list:
    """Fetch all citations for a domain, paginating automatically."""
    citations = []
    page = 1
    has_next = True

    while has_next:
        params = {'page': page, 'limit': 100, **(filters or {})}
        res = requests.get(
            f'{API_BASE}/domains/{domain_id}/explorer/citations',
            headers=HEADERS,
            params=params,
        )
        data = res.json()
        citations.extend(data['data'])
        has_next = data['hasNext']
        page += 1

    return citations


def enrich_urls(domain_id: str, urls: list, report_id: str, topic_id: str = None) -> dict:
    """Enrich URLs in batches of 100."""
    enrichment = {}

    for i in range(0, len(urls), 100):
        batch = urls[i:i + 100]
        body = {'urls': batch, 'reportId': report_id}
        if topic_id:
            body['topicId'] = topic_id

        res = requests.post(
            f'{API_BASE}/domains/{domain_id}/sources/enrichment',
            headers=HEADERS,
            json=body,
        )
        enrichment.update(res.json())

    return enrichment


def get_citations_with_enrichment(domain_id: str, report_id: str) -> list:
    """Fetch citations and enrich their sources."""
    # 1. Fetch
    citations = fetch_all_citations(domain_id, {'latestOnly': 'true'})

    # 2. Collect unique URLs
    urls = list({c['link'] for c in citations if c.get('link')})

    # 3. Enrich
    enrichment = enrich_urls(domain_id, urls, report_id)

    # 4. Merge
    for citation in citations:
        citation['enrichment'] = enrichment.get(citation.get('link'))

    return citations


# Usage
results = get_citations_with_enrichment('your-domain-id', 'your-report-id')

for row in results:
    print(f"[{row['promptCategory']}] {row['source']}")
    e = row.get('enrichment')
    if e and e.get('sourceCategory'):
        print(f"  Category: {e['sourceCategory']}")
    if e and e.get('detectedBrands'):
        for brand in e['detectedBrands']:
            label = 'own' if brand['isBrand'] else 'competitor'
            print(f"  Brand: {brand['name']} ({label}, {brand['count']} mentions)")