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
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 on each result
Geographic search Find articles that mention places near a point or inside a bounding box; optional include=counts 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:

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):

  • include=counts (or "include": ["counts"] on POST semantic search) — populates counts and embedded; they are otherwise 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