Profile: aggregation

Profile Schema

The aggregation profile specifies a document that contains a curated list of “child” documents. This list is represented by a list of links in the items array.

The documents aggregated by this document are considered part of this document’s ordered collection. For more information on collections, see the documentation on collections.


Aggregation documents are required to have an items array. items will contain zero or more relative links to CDS documents (ex: /v1/documents/1002). These links, like all CDS document links, are not necessarily valid document links; clients should query CDS itself for the individual documents (or transclude the request) to check link validity.

The relatedNewsletterIds field is a gated enum of accepted values. Those values are:

  • money
  • invisibilia
  • news
  • ed
  • politics
  • code-switch
  • goats-and-soda
  • books
  • music
  • pop-culture
  • health
  • public-editor
  • npr-extra
  • student-podcast-challenge
  • life-kit
  • life-kit-sleep
  • the-new-normal
  • best-of-npr
  • consider-this
  • breaking-news
  • scotts-thoughts
  • tiny-desk-contest
  • body-electric
Name Type Required? Explanation
items array Yes see items section below for more information
relatedNewsletterIds array No NPR-specific string array of newsletter abbreviations associated with this aggregation.


Some notes about the items array:

  • The items array can be empty
  • There can be no more than 100 entries in the items array
  • The items array should be considered already sorted by publishers
  • items links cannot have rels

Example aggregation document

  "id": "12345",
  "profiles": [
      "href": "/v1/profiles/aggregation"
      "href": "/v1/profiles/document"
  "relatedNewsletterIds" : [
  "items": [
      "href": "/v1/documents/1111"
      "href": "/v1/documents/2222"
      "href": "/v1/documents/3333"

© 2024 npr