Skip to content

Mentions

Mentions are evidence rows that link articles to people, organizations, and locations. Each mention includes a display label, optional link to a canonical record, mention nature, and text spans showing where the reference appears in the story.

How mention queries are organized

Mentions can be reached from several starting points:

Starting point Use when Doc
Project-wide Search mentions across all articles in a project List and search
Article-first You have an article and want its mentions Detail endpoints
Entity-first (people) You have a person and want their stories or mention evidence List articles, List mentions
Entity-first (organizations) You have an organization and want their stories or mention evidence List articles, List mentions
Entity-first (locations) You have a place and want its stories or mention evidence List articles, List mentions
Entity mention timeline You want mention counts by publication date for one entity Mention timeline

Project-wide routes search across articles. Article-first routes return mentions for one story. Entity-first routes return mentions for one canonical record across the project, using the same nature, article metadata, publication date, and quote filters as List and search, plus entity-specific sort and sort_direction.

Mention object (shared fields)

Mention responses vary slightly by route, but commonly include:

  • mention_id — mention id (not on List mentions; present on typed and entity-first routes)
  • label — display label for the reference
  • entity_type — person, organization, or location (project-wide search only; omitted on entity-first routes)
  • nature — editorial role when set — values depend on entity type; see Mention Meta
  • canonical — linked canonical record (id, slug, label) when available (project-wide search only)
  • evidence — first occurrence text span on list routes: mention_text, quote, start_char, and end_char
  • occurrences — all non-suppressed spans on Get mention
  • article — article summary (id, headline, url, pub_date) on project-wide and entity-first routes

Several list routes accept quote=true to return only mentions whose first evidence span is a quote — List mentions, List and search, and entity-first List mentions routes.

Entity-first mention lists (people, organizations, locations) share the article and mention filter vocabulary with project-wide search. They add sort / sort_direction, echo the canonical {type}_id and label, and omit redundant fields such as entity_type and canonical on each item.

Endpoints

Project-wide

Method Path Doc
GET …/mentions/{entity_type}/{mention_id} Get mention
GET …/mentions/search List and search
GET …/mentions/facets Mention facets

Article-first

Method Path Doc
GET …/articles/{article_id}/mentions List mentions
GET …/articles/{article_id}/people List people
GET …/articles/{article_id}/organizations List organizations
GET …/articles/{article_id}/locations List locations

Entity-first

Method Path Doc
GET …/people/{person_id}/articles List articles
GET …/people/{person_id}/mentions List mentions
GET …/organizations/{organization_id}/articles List articles
GET …/organizations/{organization_id}/mentions List mentions
GET …/locations/{location_id}/articles List articles
GET …/locations/{location_id}/mentions List mentions

Planned

Method Path Purpose
POST …/mentions/semantic-search Natural-language mention search