Skip to content

Articles

Articles are a first-class resource in Backfield. Use article endpoints to find stories, retrieve article summaries, and explore the people, organizations, locations, and images connected to a story.

Article responses include headline, source information, publication date, metadata tags, and a truncated preview (max 280 characters).

How article data is structured

Each article has a detail endpoint, search endpoints, and separate detail endpoints for larger related data.

Endpoint type Use when
Detail Show one article's summary data, inline images (up to 10), optional counts, optional full body via include=text
List and search Find articles by exact terms, metadata, or date; optional include=counts or include=images on each result
Article facets Convenience wrapper to populate article search filter controls in one call — see Metadata
Semantic search Find conceptually related articles with natural language; optional include=counts or include=images on each result
Geographic search Find articles that mention places near a point or inside a bounding box; optional include=counts or include=images on each result
Geo cells H3 hex coverage map with distinct-article counts per cell; batch drill-down for multi-cell selections
Detail endpoints Load related mentions, people, organizations, locations, custom records, or images

This keeps article detail responses fast and predictable. If you need related data beyond inline images and counts, request the slice you need from detail endpoints.

Endpoints

Method Path Doc
GET …/articles/{article_id} Get article
GET …/articles/search List and search
GET …/articles/facets Article facets
GET …/articles/metadata/types List metadata types
GET …/articles/metadata/types/{meta_type}/values List metadata values
GET …/articles/{article_id}/metadata Get article metadata
POST …/articles/semantic-search Semantic search
GET …/articles/geo-search Geographic search
GET …/articles/geo-cells Coverage
GET …/articles/geo-cells/{h3_cell} List articles
POST …/articles/geo-cells/query Batch query
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
GET …/articles/{article_id}/custom-records List custom records
GET …/articles/{article_id}/images List images

Article object

The article list shape is shared across List and search, Semantic search, and Geographic search results (geo search adds matching_locations on each item). See Get article for the full field reference.

Core fields (list and detail):

  • id, headline, url, author, pub_date
  • source — publication or outlet (id, name) when known; null otherwise
  • metadata — tags from article meta (meta_type, category, confidence)
  • preview — truncated body snippet (max 280 characters)

Detail-only (unless requested on list/search routes):

  • images — up to 10 inline image rows on Get article, or on list/search routes with include=images

Optional embeds on Get article:

  • include=counts — populates counts (mention and entity totals, image count, custom record counts) and embedded; both are otherwise null
  • include=text — adds text (full article body; preview is always included)

Optional embeds on list/search routes (List and search, Semantic search, Geographic search, and entity article lists):

  • include=counts (or "include": ["counts"] on POST semantic search) — populates counts and embedded; they are otherwise null
  • include=images (or "include": ["images"] on POST semantic search) — populates images with up to 10 inline image rows; otherwise images is null

Topic categories appear in metadata[] with meta_type=topic. Filter with meta=topic:<category> on any article-metadata filter endpoint — see Article Meta.

What article responses do not include

  • Full article body on list/search routes (use Get article with include=text)
  • Full mention or location lists (use the detail endpoints)
  • Full image lists beyond 10 rows (use List images; list/search routes return up to 10 inline images with include=images)