Inline Citations & Sources Enrichment

Retrieve, filter, and enrich the citations that AI models return when answering brand-related prompts

Overview

When LLMs answer prompts about your brand, they often include URLs directly within their response text. Getmint extracts these domains from the raw LLM output and stores them as inline citations — the responseDomains field on each visibility detailed result, enriched with domain categories.

These citations are accessible through three layers:

API	Purpose
Raw LLM Results	Access the full LLM prompt/response pairs with their `responseDomains` (inline citations) and structured `citations[]`
Explorer Citations	Paginated, filterable table aggregating citations across all analysis types
Sources Enrichment	Adds category and brand-mention metadata to a set of citation URLs

All endpoints require either a session token or an API key passed via the X-API-Key header.

Inline Citations (Raw LLM Results)

Inline citations are the responseDomains found in each visibility detailed result — domains extracted directly from the LLM response text, enriched with domain categories. They represent the sources the model referenced inline when answering a prompt.

Additionally, raw results may include a structured citations[] array with richer metadata (URL, title, snippet, brand mention detection).

Both are returned by the Raw Results endpoints for each analysis type.

Endpoint

GET /api/domains/:domainId/topics/:topicId/visibility/raw-results

Only the visibility raw results endpoint returns inline citations (responseDomains) and structured citations (citations[]).

For aggregated citations across all analysis types, use the Explorer Citations endpoint below.

Query Parameters (shared across all raw results)

Parameter	Type	Default	Description
`page`	integer	`1`	Page number (1-based)
`limit`	integer	`50`	Items per page (max 100)
`startDate`	ISO 8601 date	—	Start of the report date range
`endDate`	ISO 8601 date	—	End of the report date range
`models`	string (comma-separated)	—	Filter by LLM models
`latestOnly`	boolean	`false`	Return only the most recent report

Inline Citation Object (`responseDomains`)

Each entry in the responseDomains array represents a domain found inline in the LLM response text:

Field	Type	Description
`domain`	string	Domain extracted from the LLM response text (e.g. `"techcrunch.com"`)
`categories`	string[]?	Domain categories (e.g. `["Internet and Telecom > Technology News"]`)

Structured Citation Object (`citations[]`)

Each citation in the citations[] array contains:

Field	Type	Description
`url`	string?	URL cited by the LLM
`title`	string?	Page title extracted from the citation
`text`	string?	Text snippet from the cited source
`website`	string?	Domain name of the cited source
`brandMentioned`	boolean?	Whether your brand was detected in this citation (visibility only)
`brandMentionContext`	string?	~50 character context window around the brand mention (visibility only)

Example Request (Visibility)

curl "https://api.getmint.ai/api/domains/YOUR_DOMAIN_ID/topics/YOUR_TOPIC_ID/visibility/raw-results?\
latestOnly=true&models=gpt-5" \
  -H "X-API-Key: YOUR_API_KEY"

Example Response (Visibility)

{
  "results": [
    {
      "id": "507f1f77bcf86cd799439011-0",
      "prompt": "What are the best payment processing solutions?",
      "response": "Based on my research, several payment processing solutions stand out...",
      "model": "gpt-5",
      "brandMentioned": true,
      "citations": [
        {
          "url": "https://techcrunch.com/2025/01/10/payment-apis-compared",
          "title": "Payment APIs Compared: Stripe vs Square vs PayPal",
          "text": "Stripe continues to lead in developer experience with its well-documented APIs...",
          "website": "techcrunch.com",
          "brandMentioned": true,
          "brandMentionContext": "...Stripe continues to lead in developer experience..."
        },
        {
          "url": "https://g2.com/products/stripe/reviews",
          "title": "Stripe Reviews 2025",
          "text": "Rated 4.5/5 by over 3,000 developers...",
          "website": "g2.com",
          "brandMentioned": true,
          "brandMentionContext": "...Stripe Reviews 2025..."
        }
      ],
      "topOfMind": ["Stripe", "PayPal", "Square"],
      "responseDomains": [
        {
          "domain": "techcrunch.com",
          "categories": ["Internet and Telecom > Technology News"]
        }
      ],
      "reportDate": "2025-03-15T10:30:00.000Z",
      "reportId": "507f1f77bcf86cd799439011"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 24,
    "totalPages": 1
  }
}

Visibility-Specific Fields

Beyond the shared id, prompt, response, model, reportDate, and reportId fields, visibility raw results include:

Field	Type	Description
`brandMentioned`	boolean	Whether the brand was mentioned anywhere in the LLM response
`citations`	CitationDto[]	Structured citations extracted from the response (see structure above)
`topOfMind`	string[]	Company/brand names mentioned prominently in the response
`responseDomains`	ResponseDomainDto[]?	Inline citations — domains extracted from the response text, enriched with domain categories

Explorer Citations

Endpoint

GET /api/domains/:domainId/explorer/citations

Returns a paginated list of citations aggregated from the four detailed-result collections: topic_visibility_detailed_results, topic_competition_detailed_results, domain_sentiment_detailed_results, and domain_alignment_detailed_results.

Responses are cached for 60 seconds.

Query Parameters

Pagination

Parameter	Type	Default	Constraints	Description
`page`	integer	`1`	min 1	Page number (1-based)
`limit`	integer	`50`	min 1, max 1000	Items per page

Global Filters

Parameter	Type	Default	Description
`startDate`	ISO 8601 date	6 months ago	Start of the report date range. Omit to default to the last 6 months; an explicit start is honoured at any length.
`endDate`	ISO 8601 date	now	End of the report date range
`models`	string (comma-separated)	—	LLM models to include, e.g. `gpt-5,claude-sonnet-4-5-20250929`
`latestOnly`	boolean	`false`	Return only the most recent report instead of the full date range

Table Filters

Parameter	Type	Description
`searchQuery`	string	Partial match on the prompt text
`source`	string	Partial match on the source domain name
`linkDomain`	string[] (comma-separated)	Multi-select filter on citation domain
`promptCategory`	string[] (comma-separated)	One or more of: `visibility`, `competition`, `sentiment`, `alignment`
`model`	string[] (comma-separated)	Multi-select filter on LLM model
`promptText`	string[] (repeated param)	Filter by exact prompt texts. Not comma-separated — use repeated query params (`promptText=a&promptText=b`) because prompts can contain commas
`topicName`	string[] (comma-separated)	Multi-select filter on topic name (visibility/competition only)

Sorting

Parameter	Type	Default	Allowed values
`sortBy`	string	—	`searchQuery`, `source`, `linkDomain`, `model`, `promptCategory`, `topicName`
`sortOrder`	string	`asc`	`asc`, `desc`

Example Request

curl "https://api.getmint.ai/api/domains/YOUR_DOMAIN_ID/explorer/citations?\
page=1&limit=20&\
promptCategory=visibility,sentiment&\
models=gpt-5&\
sortBy=source&sortOrder=desc" \
  -H "X-API-Key: YOUR_API_KEY"

Example Response

{
  "data": [
    {
      "fanOutQueries": ["best payment processing APIs 2025"],
      "source": "techcrunch.com",
      "link": "https://techcrunch.com/2025/01/10/payment-apis-compared",
      "linkDomain": "techcrunch.com",
      "model": "gpt-5",
      "promptCategory": "visibility",
      "promptText": "What are the best payment processing solutions?",
      "promptId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "topicId": "f9e8d7c6-b5a4-3210-fedc-ba0987654321",
      "topicName": "Payment Processing"
    },
    {
      "fanOutQueries": ["Stripe developer sentiment 2025"],
      "source": "g2.com",
      "link": "https://g2.com/products/stripe/reviews",
      "linkDomain": "g2.com",
      "model": "gpt-5",
      "promptCategory": "sentiment",
      "promptText": "How do developers feel about Stripe?",
      "promptId": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
    }
  ],
  "total": 142,
  "page": 1,
  "limit": 20,
  "totalPages": 8,
  "hasNext": true,
  "hasPrev": false,
  "filterOptions": {
    "linkDomains": ["techcrunch.com", "g2.com", "stripe.com", "forbes.com"],
    "models": ["gpt-5", "claude-sonnet-4-5-20250929", "gemini-2.5-pro"],
    "promptCategories": ["visibility", "sentiment", "competition", "alignment"],
    "promptTexts": [
      "What are the best payment processing solutions?",
      "How do developers feel about Stripe?"
    ],
    "topicNames": ["Payment Processing", "Developer Tools"]
  }
}

filterOptions returns the distinct values from the full filtered dataset (before pagination). Use these to populate multi-select dropdowns in your UI.

Response Fields

Field	Type	Description
`fanOutQueries`	string[]	Web-search queries the LLM issued to produce the citation
`source`	string	Extracted domain of the cited URL
`link`	string?	Full URL of the citation (may be absent for some models)
`linkDomain`	string	Normalized domain extracted from `link`
`model`	string	LLM model that generated the response
`promptCategory`	string	One of `visibility`, `competition`, `sentiment`, `alignment`
`promptText`	string?	The prompt that triggered the response
`promptId`	string?	UUID of the prompt
`topicId`	string?	Topic UUID (visibility and competition only)
`topicName`	string?	Topic name (visibility and competition only)

Sources Enrichment

Endpoint

POST /api/domains/:domainId/sources/enrichment

Takes a batch of source URLs and returns enrichment metadata for each: the domain category and any brand mentions detected during source crawling.

Request Body

Field	Type	Required	Constraints	Description
`urls`	string[]	Yes	Max 100 items	Source URLs to enrich
`reportId`	string	Yes	—	Report ID that generated the citations (used to look up crawl results)
`topicId`	string	No	—	Topic ID to resolve market/language for category lookup

Example Request

curl -X POST "https://api.getmint.ai/api/domains/YOUR_DOMAIN_ID/sources/enrichment" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "urls": [
      "https://techcrunch.com/2025/01/10/payment-apis-compared",
      "https://g2.com/products/stripe/reviews",
      "https://forbes.com/advisor/business/best-payment-processing"
    ],
    "reportId": "507f1f77bcf86cd799439011",
    "topicId": "f9e8d7c6-b5a4-3210-fedc-ba0987654321"
  }'

Example Response

{
  "https://techcrunch.com/2025/01/10/payment-apis-compared": {
    "sourceCategory": "Internet and Telecom > Technology News",
    "detectedBrands": [
      { "name": "Stripe", "count": 12, "isBrand": true },
      { "name": "PayPal", "count": 8, "isBrand": false },
      { "name": "Square", "count": 5, "isBrand": false }
    ],
    "contentLength": 4820,
    "wordCount": 780,
    "publicationDate": "2025-01-10T00:00:00.000Z",
    "contentLinks": {
      "internal": ["https://techcrunch.com/about"],
      "external": ["https://stripe.com/", "https://paypal.com/"]
    }
  },
  "https://g2.com/products/stripe/reviews": {
    "sourceCategory": "Computers and Electronics > Software Reviews",
    "detectedBrands": [
      { "name": "Stripe", "count": 34, "isBrand": true }
    ],
    "contentLength": 9210,
    "wordCount": 1540,
    "contentLinks": {
      "internal": [],
      "external": ["https://stripe.com/"]
    }
  }
}

URLs with no enrichment data (no category found and no crawl results) are omitted from the response. An empty object {} means no URLs could be enriched.

Response Fields

Field	Type	Description
`sourceCategory`	string?	Hierarchical category, joined with `>` (e.g. `"Internet and Telecom > Technology News"`)
`detectedBrands`	object[]?	Brand mentions found during source crawl. Only present if at least one brand was detected
`detectedBrands[].name`	string	Brand or competitor name
`detectedBrands[].count`	number	Number of times the brand was mentioned on the page
`detectedBrands[].isBrand`	boolean	`true` = your own brand (domain owner), `false` = competitor
`contentLength`	number?	Visible-text character count of the crawled page. Present when available from a successful crawl result
`wordCount`	number?	Visible-text word count of the crawled page. Present when available from a successful crawl result
`publicationDate`	string?	Publication / creation date extracted from the page (ISO 8601). Omitted when none could be parsed
`contentLinks`	object?	Links found in the page content. Present when available from a successful crawl result. Each list is capped at 100 entries
`contentLinks.internal`	string[]	Absolute URLs pointing to the same host as the source page (a leading `www.` is ignored, so `www.example.com` counts as internal for `example.com`)
`contentLinks.external`	string[]	Absolute URLs pointing to a different host than the source page (after ignoring a leading `www.`)
`lastCheckedAt`	string?	ISO 8601 timestamp of when this source page was last checked. Falls back to the daily crawl time when no manual re-check has run. Present for every successful crawl result

Extraction Rules

The enrichment pipeline combines two data sources:

Domain Category Lookup

Each unique domain from the input URLs is sent to DomainCategoryLookupService, which resolves each domain's category. Categories are hierarchical strings joined with >.

If the lookup fails or returns no categories, sourceCategory is omitted for that URL.

Brand Mention Detection

The system looks up crawl results from SourceCrawlResultRepository using the reportId and URL. For each crawled page:

Domain matches (own brand) are reported with isBrand: true
Competitor matches are reported with isBrand: false
Only brands with count > 0 are included
If no crawl result exists for the URL, detectedBrands is omitted

Content Metadata Extraction

The same crawl pass that detects brand mentions also extracts structured metadata from the page HTML:

contentLength / wordCount — character and word count of the page's visible text
publicationDate — parsed from JSON-LD datePublished, <meta property="article:published_time">, related meta tags, or <time datetime>, in that order. Omitted when none parse to a valid date
contentLinks — every <a href> resolved to an absolute URL, deduplicated, and split into internal (same host) and external (different host); each list is capped at 100 entries

These fields come from the crawl result, so they are present only for URLs that were crawled successfully. Unparseable or missing values degrade gracefully — never an error.

Error Codes

HTTP Status	Code	When	Resolution
400	Bad Request	Validation failure: missing `urls`/`reportId`, `limit > 1000`, invalid `sortBy` value, non-ISO date strings	Check request body/query params against the schema above
401	Unauthorized	Missing or invalid API key / session token, or no organization associated	Verify your `X-API-Key` header or session cookie
404	Not Found	`domainId` does not exist or does not belong to your organization	Confirm the domain ID via the domains list endpoint
429	Too Many Requests	Rate limit exceeded (200 req/min default)	Back off and retry after `X-RateLimit-Reset` seconds. See Rate Limits
500	Internal Server Error	Aggregation pipeline failure or upstream service error	Retry after a short delay; contact support if persistent

Common Validation Errors

{
  "statusCode": 400,
  "message": [
    "urls must contain no more than 100 elements",
    "reportId must be a string"
  ],
  "error": "Bad Request"
}

{
  "statusCode": 400,
  "message": [
    "limit must not be greater than 1000",
    "sortBy must be one of the following values: searchQuery, source, linkDomain, model, promptCategory, topicName"
  ],
  "error": "Bad Request"
}

Edge Cases

Compatibility Notes

Array query params: All comma-separated array filters (models, linkDomain, promptCategory, model, topicName) also accept repeated query params (?model=gpt-5&model=gemini-2.5-pro). Both formats are supported.

The filterOptions object in the citations response always reflects the full filtered dataset (after global + table filters, before pagination). It will not include values that are filtered out by other active filters.
totalPages is computed as Math.ceil(total / limit) with a minimum of 1 (even when total is 0).
The latestOnly flag overrides startDate/endDate — when true, date range filters are ignored and only the most recent report is returned.

API Reference

See the full interactive API specification (try requests, inspect schemas):

Raw Results (with inline citations & structured citations):
- Visibility Raw Results — GET /domains/:domainId/topics/:topicId/visibility/raw-results
Aggregated & Enrichment:
- Explorer Citations — GET /domains/:domainId/explorer/citations
- Sources Enrichment — POST /domains/:domainId/sources/enrichment

Next Steps

Developer Guide: Leveraging Citations & Enrichment — practical patterns for building on these APIs
Rate Limits — understand throttling policies

Overview

These citations are accessible through three layers:

API	Purpose
Raw LLM Results	Access the full LLM prompt/response pairs with their `responseDomains` (inline citations) and structured `citations[]`
Explorer Citations	Paginated, filterable table aggregating citations across all analysis types
Sources Enrichment	Adds category and brand-mention metadata to a set of citation URLs

All endpoints require either a session token or an API key passed via the X-API-Key header.

Inline Citations (Raw LLM Results)

Additionally, raw results may include a structured citations[] array with richer metadata (URL, title, snippet, brand mention detection).

Both are returned by the Raw Results endpoints for each analysis type.

Endpoint

GET /api/domains/:domainId/topics/:topicId/visibility/raw-results

Only the visibility raw results endpoint returns inline citations (responseDomains) and structured citations (citations[]).

For aggregated citations across all analysis types, use the Explorer Citations endpoint below.

Query Parameters (shared across all raw results)

Parameter	Type	Default	Description
`page`	integer	`1`	Page number (1-based)
`limit`	integer	`50`	Items per page (max 100)
`startDate`	ISO 8601 date	—	Start of the report date range
`endDate`	ISO 8601 date	—	End of the report date range
`models`	string (comma-separated)	—	Filter by LLM models
`latestOnly`	boolean	`false`	Return only the most recent report

Inline Citation Object (`responseDomains`)

Each entry in the responseDomains array represents a domain found inline in the LLM response text:

Field	Type	Description
`domain`	string	Domain extracted from the LLM response text (e.g. `"techcrunch.com"`)
`categories`	string[]?	Domain categories (e.g. `["Internet and Telecom > Technology News"]`)

Structured Citation Object (`citations[]`)

Each citation in the citations[] array contains:

Field	Type	Description
`url`	string?	URL cited by the LLM
`title`	string?	Page title extracted from the citation
`text`	string?	Text snippet from the cited source
`website`	string?	Domain name of the cited source
`brandMentioned`	boolean?	Whether your brand was detected in this citation (visibility only)
`brandMentionContext`	string?	~50 character context window around the brand mention (visibility only)

Example Request (Visibility)

curl "https://api.getmint.ai/api/domains/YOUR_DOMAIN_ID/topics/YOUR_TOPIC_ID/visibility/raw-results?\
latestOnly=true&models=gpt-5" \
  -H "X-API-Key: YOUR_API_KEY"

Example Response (Visibility)

{
  "results": [
    {
      "id": "507f1f77bcf86cd799439011-0",
      "prompt": "What are the best payment processing solutions?",
      "response": "Based on my research, several payment processing solutions stand out...",
      "model": "gpt-5",
      "brandMentioned": true,
      "citations": [
        {
          "url": "https://techcrunch.com/2025/01/10/payment-apis-compared",
          "title": "Payment APIs Compared: Stripe vs Square vs PayPal",
          "text": "Stripe continues to lead in developer experience with its well-documented APIs...",
          "website": "techcrunch.com",
          "brandMentioned": true,
          "brandMentionContext": "...Stripe continues to lead in developer experience..."
        },
        {
          "url": "https://g2.com/products/stripe/reviews",
          "title": "Stripe Reviews 2025",
          "text": "Rated 4.5/5 by over 3,000 developers...",
          "website": "g2.com",
          "brandMentioned": true,
          "brandMentionContext": "...Stripe Reviews 2025..."
        }
      ],
      "topOfMind": ["Stripe", "PayPal", "Square"],
      "responseDomains": [
        {
          "domain": "techcrunch.com",
          "categories": ["Internet and Telecom > Technology News"]
        }
      ],
      "reportDate": "2025-03-15T10:30:00.000Z",
      "reportId": "507f1f77bcf86cd799439011"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 24,
    "totalPages": 1
  }
}

Visibility-Specific Fields

Beyond the shared id, prompt, response, model, reportDate, and reportId fields, visibility raw results include:

Field	Type	Description
`brandMentioned`	boolean	Whether the brand was mentioned anywhere in the LLM response
`citations`	CitationDto[]	Structured citations extracted from the response (see structure above)
`topOfMind`	string[]	Company/brand names mentioned prominently in the response
`responseDomains`	ResponseDomainDto[]?	Inline citations — domains extracted from the response text, enriched with domain categories

Explorer Citations

Endpoint

GET /api/domains/:domainId/explorer/citations

Responses are cached for 60 seconds.

Query Parameters

Pagination

Parameter	Type	Default	Constraints	Description
`page`	integer	`1`	min 1	Page number (1-based)
`limit`	integer	`50`	min 1, max 1000	Items per page

Global Filters

Parameter	Type	Default	Description
`startDate`	ISO 8601 date	6 months ago	Start of the report date range. Omit to default to the last 6 months; an explicit start is honoured at any length.
`endDate`	ISO 8601 date	now	End of the report date range
`models`	string (comma-separated)	—	LLM models to include, e.g. `gpt-5,claude-sonnet-4-5-20250929`
`latestOnly`	boolean	`false`	Return only the most recent report instead of the full date range

Table Filters

Parameter	Type	Description
`searchQuery`	string	Partial match on the prompt text
`source`	string	Partial match on the source domain name
`linkDomain`	string[] (comma-separated)	Multi-select filter on citation domain
`promptCategory`	string[] (comma-separated)	One or more of: `visibility`, `competition`, `sentiment`, `alignment`
`model`	string[] (comma-separated)	Multi-select filter on LLM model
`promptText`	string[] (repeated param)	Filter by exact prompt texts. Not comma-separated — use repeated query params (`promptText=a&promptText=b`) because prompts can contain commas
`topicName`	string[] (comma-separated)	Multi-select filter on topic name (visibility/competition only)

Sorting

Parameter	Type	Default	Allowed values
`sortBy`	string	—	`searchQuery`, `source`, `linkDomain`, `model`, `promptCategory`, `topicName`
`sortOrder`	string	`asc`	`asc`, `desc`

Example Request

curl "https://api.getmint.ai/api/domains/YOUR_DOMAIN_ID/explorer/citations?\
page=1&limit=20&\
promptCategory=visibility,sentiment&\
models=gpt-5&\
sortBy=source&sortOrder=desc" \
  -H "X-API-Key: YOUR_API_KEY"

Example Response

{
  "data": [
    {
      "fanOutQueries": ["best payment processing APIs 2025"],
      "source": "techcrunch.com",
      "link": "https://techcrunch.com/2025/01/10/payment-apis-compared",
      "linkDomain": "techcrunch.com",
      "model": "gpt-5",
      "promptCategory": "visibility",
      "promptText": "What are the best payment processing solutions?",
      "promptId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "topicId": "f9e8d7c6-b5a4-3210-fedc-ba0987654321",
      "topicName": "Payment Processing"
    },
    {
      "fanOutQueries": ["Stripe developer sentiment 2025"],
      "source": "g2.com",
      "link": "https://g2.com/products/stripe/reviews",
      "linkDomain": "g2.com",
      "model": "gpt-5",
      "promptCategory": "sentiment",
      "promptText": "How do developers feel about Stripe?",
      "promptId": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
    }
  ],
  "total": 142,
  "page": 1,
  "limit": 20,
  "totalPages": 8,
  "hasNext": true,
  "hasPrev": false,
  "filterOptions": {
    "linkDomains": ["techcrunch.com", "g2.com", "stripe.com", "forbes.com"],
    "models": ["gpt-5", "claude-sonnet-4-5-20250929", "gemini-2.5-pro"],
    "promptCategories": ["visibility", "sentiment", "competition", "alignment"],
    "promptTexts": [
      "What are the best payment processing solutions?",
      "How do developers feel about Stripe?"
    ],
    "topicNames": ["Payment Processing", "Developer Tools"]
  }
}

filterOptions returns the distinct values from the full filtered dataset (before pagination). Use these to populate multi-select dropdowns in your UI.

Response Fields

Field	Type	Description
`fanOutQueries`	string[]	Web-search queries the LLM issued to produce the citation
`source`	string	Extracted domain of the cited URL
`link`	string?	Full URL of the citation (may be absent for some models)
`linkDomain`	string	Normalized domain extracted from `link`
`model`	string	LLM model that generated the response
`promptCategory`	string	One of `visibility`, `competition`, `sentiment`, `alignment`
`promptText`	string?	The prompt that triggered the response
`promptId`	string?	UUID of the prompt
`topicId`	string?	Topic UUID (visibility and competition only)
`topicName`	string?	Topic name (visibility and competition only)

Sources Enrichment

Endpoint

POST /api/domains/:domainId/sources/enrichment

Takes a batch of source URLs and returns enrichment metadata for each: the domain category and any brand mentions detected during source crawling.

Request Body

Field	Type	Required	Constraints	Description
`urls`	string[]	Yes	Max 100 items	Source URLs to enrich
`reportId`	string	Yes	—	Report ID that generated the citations (used to look up crawl results)
`topicId`	string	No	—	Topic ID to resolve market/language for category lookup

Example Request

curl -X POST "https://api.getmint.ai/api/domains/YOUR_DOMAIN_ID/sources/enrichment" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "urls": [
      "https://techcrunch.com/2025/01/10/payment-apis-compared",
      "https://g2.com/products/stripe/reviews",
      "https://forbes.com/advisor/business/best-payment-processing"
    ],
    "reportId": "507f1f77bcf86cd799439011",
    "topicId": "f9e8d7c6-b5a4-3210-fedc-ba0987654321"
  }'

Example Response

{
  "https://techcrunch.com/2025/01/10/payment-apis-compared": {
    "sourceCategory": "Internet and Telecom > Technology News",
    "detectedBrands": [
      { "name": "Stripe", "count": 12, "isBrand": true },
      { "name": "PayPal", "count": 8, "isBrand": false },
      { "name": "Square", "count": 5, "isBrand": false }
    ],
    "contentLength": 4820,
    "wordCount": 780,
    "publicationDate": "2025-01-10T00:00:00.000Z",
    "contentLinks": {
      "internal": ["https://techcrunch.com/about"],
      "external": ["https://stripe.com/", "https://paypal.com/"]
    }
  },
  "https://g2.com/products/stripe/reviews": {
    "sourceCategory": "Computers and Electronics > Software Reviews",
    "detectedBrands": [
      { "name": "Stripe", "count": 34, "isBrand": true }
    ],
    "contentLength": 9210,
    "wordCount": 1540,
    "contentLinks": {
      "internal": [],
      "external": ["https://stripe.com/"]
    }
  }
}

URLs with no enrichment data (no category found and no crawl results) are omitted from the response. An empty object {} means no URLs could be enriched.

Response Fields

Field	Type	Description
`sourceCategory`	string?	Hierarchical category, joined with `>` (e.g. `"Internet and Telecom > Technology News"`)
`detectedBrands`	object[]?	Brand mentions found during source crawl. Only present if at least one brand was detected
`detectedBrands[].name`	string	Brand or competitor name
`detectedBrands[].count`	number	Number of times the brand was mentioned on the page
`detectedBrands[].isBrand`	boolean	`true` = your own brand (domain owner), `false` = competitor
`contentLength`	number?	Visible-text character count of the crawled page. Present when available from a successful crawl result
`wordCount`	number?	Visible-text word count of the crawled page. Present when available from a successful crawl result
`publicationDate`	string?	Publication / creation date extracted from the page (ISO 8601). Omitted when none could be parsed
`contentLinks`	object?	Links found in the page content. Present when available from a successful crawl result. Each list is capped at 100 entries
`contentLinks.internal`	string[]	Absolute URLs pointing to the same host as the source page (a leading `www.` is ignored, so `www.example.com` counts as internal for `example.com`)
`contentLinks.external`	string[]	Absolute URLs pointing to a different host than the source page (after ignoring a leading `www.`)
`lastCheckedAt`	string?	ISO 8601 timestamp of when this source page was last checked. Falls back to the daily crawl time when no manual re-check has run. Present for every successful crawl result

Extraction Rules

The enrichment pipeline combines two data sources:

Domain Category Lookup

Each unique domain from the input URLs is sent to DomainCategoryLookupService, which resolves each domain's category. Categories are hierarchical strings joined with >.

If the lookup fails or returns no categories, sourceCategory is omitted for that URL.

Brand Mention Detection

The system looks up crawl results from SourceCrawlResultRepository using the reportId and URL. For each crawled page:

Domain matches (own brand) are reported with isBrand: true
Competitor matches are reported with isBrand: false
Only brands with count > 0 are included
If no crawl result exists for the URL, detectedBrands is omitted

Content Metadata Extraction

The same crawl pass that detects brand mentions also extracts structured metadata from the page HTML:

contentLength / wordCount — character and word count of the page's visible text
publicationDate — parsed from JSON-LD datePublished, <meta property="article:published_time">, related meta tags, or <time datetime>, in that order. Omitted when none parse to a valid date
contentLinks — every <a href> resolved to an absolute URL, deduplicated, and split into internal (same host) and external (different host); each list is capped at 100 entries

These fields come from the crawl result, so they are present only for URLs that were crawled successfully. Unparseable or missing values degrade gracefully — never an error.

Error Codes

HTTP Status	Code	When	Resolution
400	Bad Request	Validation failure: missing `urls`/`reportId`, `limit > 1000`, invalid `sortBy` value, non-ISO date strings	Check request body/query params against the schema above
401	Unauthorized	Missing or invalid API key / session token, or no organization associated	Verify your `X-API-Key` header or session cookie
404	Not Found	`domainId` does not exist or does not belong to your organization	Confirm the domain ID via the domains list endpoint
429	Too Many Requests	Rate limit exceeded (200 req/min default)	Back off and retry after `X-RateLimit-Reset` seconds. See Rate Limits
500	Internal Server Error	Aggregation pipeline failure or upstream service error	Retry after a short delay; contact support if persistent

Common Validation Errors

{
  "statusCode": 400,
  "message": [
    "urls must contain no more than 100 elements",
    "reportId must be a string"
  ],
  "error": "Bad Request"
}

{
  "statusCode": 400,
  "message": [
    "limit must not be greater than 1000",
    "sortBy must be one of the following values: searchQuery, source, linkDomain, model, promptCategory, topicName"
  ],
  "error": "Bad Request"
}

Edge Cases

Compatibility Notes

The filterOptions object in the citations response always reflects the full filtered dataset (after global + table filters, before pagination). It will not include values that are filtered out by other active filters.
totalPages is computed as Math.ceil(total / limit) with a minimum of 1 (even when total is 0).
The latestOnly flag overrides startDate/endDate — when true, date range filters are ignored and only the most recent report is returned.

API Reference

See the full interactive API specification (try requests, inspect schemas):

Raw Results (with inline citations & structured citations):
- Visibility Raw Results — GET /domains/:domainId/topics/:topicId/visibility/raw-results
Aggregated & Enrichment:
- Explorer Citations — GET /domains/:domainId/explorer/citations
- Sources Enrichment — POST /domains/:domainId/sources/enrichment

Next Steps

Developer Guide: Leveraging Citations & Enrichment — practical patterns for building on these APIs
Rate Limits — understand throttling policies

Inline Citations & Sources Enrichment

Empty URL list in Sources Enrichment

Invalid URLs are silently skipped

promptText filter does not split on commas

topicId and topicName are visibility/competition only

Cache behavior on the citations endpoint

Sources Enrichment returns partial results

On this page

Inline Citations & Sources Enrichment

Empty URL list in Sources Enrichment

Invalid URLs are silently skipped

promptText filter does not split on commas

topicId and topicName are visibility/competition only

Cache behavior on the citations endpoint

Sources Enrichment returns partial results

On this page