GET Document
Get a single CDS document by ID
GET /v1/documents/{documentId}
Requires Auth?
Yes. See the Getting Started page for more details.
Query Params
Transclude
The only valid query param for this endpoint is transclude. Using this query param will return the requested CDS document, populated (‘transcluded’) with serialized associated data, in an additional embed field on the respective nested resource.
Transclude Fields
Please Read: As of February 2024, we are experiencing problems with the transclude parameter when used with bylines and transcript. Read more below, but do know that we are looking into improving this feature soon:
bylines: This will only work for text-only bylines. That means that the transclude will not pull in a biography document. To get a biography document you need to follow thehrefsourced in abylineDocumentsarray. See the reference-byline documentation for more information.transcript: This unfortunately is not working as expected. As mentioned we are working to resolve this. In the meantime, see this guide on fetching transcript data
The following are perhaps the most common and/or useful options:
| Value | Description |
|---|---|
collections | The CDS collection(s) to which the document belongs |
bylines | Information about individuals mentioned in the byline of a story |
layout | The display layout of a story |
transcript | The textual transcript associated with this story |
items | The items contained in an aggregation.(For instance, the individual story items in a given program-episode document) |
Sample Transcluded Responses
Click to expand.
collections
collections
{
"resources": [
{
...
"collections": [
{
"href": "/v1/documents/someProgramCollection",
"rels": [
"program"
],
"embed": {
"meta": {
"assetInternalLinkDocuments": [],
"documentLastModifiedDateTime": "2022-05-06T12:56:24.150Z",
"extensionLinks": []
},
"id": "someProgramCollection",
"title": "Some Program",
"profiles": [
{
"href": "/v1/profiles/program",
"rels": [
"type"
]
},
...
],
"owners": [
{
"href": "https://some-url.org/v4/services/someServiceId"
}
],
"brandings": [
{
"href": "https://some-url.org/v4/services/someServiceId"
}
],
"publishDateTime": "2012-01-18T06:00:00-05:00",
"authorizedOrgServiceIds": [
"someServiceId"
],
"editorialLastModifiedDateTime": "2021-12-21T16:29:36-05:00",
"images": [],
"layout": [],
"nprDisplayType": "ProgramMagazine",
"nprWebsitePath": "/programs/some-program/",
"robotsNoIndex": false,
"shortTeaser": "Some Program takes listeners around the country and the world every weekday.",
"teaser": "Some Program takes listeners around the country and the world with multi-faceted stories and commentaries every weekday. Hosts Some First Host, Some Second Host and Some Third Host bring you the latest breaking news and features to prepare you for the day.",
"webPages": [
{
"href": "https://some-url.org/programs/some-program/",
"rels": [
"canonical"
]
}
],
...
}
},
...
]
...
}
]
}
bylines
bylines
{
"resources": [
{
...
"bylines": [
{
"href": "#/assets/12345",
"embed": {
"id": "12345",
"name": "Some Displayable Name",
"profiles": [
{
"href": "/v1/profiles/byline",
"rels": [
"type"
]
},
{
"href": "/v1/profiles/document"
}
]
}
},
{
"href": "#/assets/678901",
"embed": {
"id": "678901",
"name": "Some Other Displayable Name",
"profiles": [
{
"href": "/v1/profiles/byline",
"rels": [
"type"
]
},
{
"href": "/v1/profiles/document"
}
]
}
}
],
...
}
]
}
layout
layout
{
"resources": [
{
...
"layout": [
{
"href": "#/assets/12345678-1000",
"embed": {
"id": "12345678-1000",
"profiles": [
{
"href": "/v1/profiles/text",
"rels": [
"type"
]
},
{
"href": "/v1/profiles/document"
}
],
"text": "Some text from the document"
}
}
]
...
}
]
}
items
items
{
"resources": [
{
...
"items": [
{
"href": "/v1/documents/1234567890",
"embed": {
"meta": {
"assetInternalLinkDocuments": [],
"documentLastModifiedDateTime": "2022-04-16T19:55:15.377Z",
"extensionLinks": [
{
"href": "/v1/documents/1234567890-transcript"
}
]
},
"id": "1234567890",
"title": "News brief: Some news happened",
"profiles": [
...
],
"owners": [
{
"href": "https://some-url.org/v4/services/some-owner-id"
}
],
"brandings": [
{
"href": "https://some-url.org/v4/services/some-owner-id"
}
],
"publishDateTime": "2022-04-15T05:16:00-04:00",
"collections": [
...
],
"audio": [
{
"href": "#/assets/1234567890",
"rels": [
"headline",
"primary"
]
}
],
"authorizedOrgServiceIds": [
"someOrgId"
],
"bylines": [
{
"href": "#/assets/someReporterId"
},
{
"href": "#/assets/someReporterId"
}
],
"editorialLastModifiedDateTime": "2022-04-15T08:14:47-04:00",
"layout": [],
"nprDisplayType": "NewsStory",
"nprWebsitePath": "/2022/04/15/1234567890/some-story-url",
"robotsNoIndex": false,
"teaser": "We had some NEWS! happen.",
"webPages": [
{
"href": "https://www.npr.org/2022/04/15/1234567890/news-story-item",
"rels": [
"canonical"
]
}
]
}
},
...
]
...
}
]
}
Response Codes
| Response Code | Meaning |
|---|---|
200 | Successful retrieval of doc |
{
"resources": [
{
"id": "12345",
"profiles": [
{
"href": "/v1/profiles/document"
},
{
"href": "/v1/profiles/story",
"rels": [
"type"
]
}
],
"authorizedOrgServiceIds": [
"s1",
"s350",
"s999"
],
"meta": {
"cdsSecretCode": "40723097957p345234532"
}
}
]
}
400 | Bad request |
{
"meta": {
"messages": [
"badQueryParam is an unexpected query parameter"
]
}
}
404 | Document not found |
GET Query Documents
Query CDS for documents matching provided query parameters
GET /v1/documents
Requires Auth?
Yes. See the Getting Started page for more details.
Query Params
Please see the thorough writeup on query params for this endpoint here.
This endpoint also accepts the transclude query param, the documentation for which can be found here.
Response Codes
| Response Code | Meaning |
|---|---|
200 | Successful retrieval of matching documents (NB: This endpoint will also return a 200 if no matching documents are found; the response will simply contain an empty resources array.) |
{
"resources": [
{
"id": "12345",
"profiles": [
{
"href": "/v1/profiles/document"
},
{
"href": "/v1/profiles/story",
"rels": [
"type"
]
}
],
"authorizedOrgServiceIds": [
"s1",
"s350",
"s999"
],
"meta": {
"cdsSecretCode": "40723097957p345234532"
}
}
]
}
400 | Bad request |
{
"meta": {
"messages": [
"2022-01-01...2022-12-311 are invalid showDates"
]
}
}
PUT Update Document
Update an existing CDS document, or create a new CDS doc.
PUT /v1/documents/{documentId}
Requires Auth?
Yes. See the Getting Started page for more details.
Response Codes
| Response Code | Meaning |
|---|---|
200 | Successful update / creation of doc |
{
"resources": [
{
"id": "12345",
"profiles": [
{
"href": "/v1/profiles/document"
},
{
"href": "/v1/profiles/story",
"rels": [
"type"
]
}
],
"authorizedOrgServiceIds": [
"s1",
"s350",
"s999"
],
"meta": {
"cdsSecretCode": "40723097957p345234532"
}
}
]
}
400 | Bad request |
{
"meta": {
"messages": [
"The value {...} failed to validate for the keyword \"required\".\nError: must have required property 'showDate'.\nData location: "
]
}
}
DELETE document
Delete a single CDS document by ID
DELETE /v1/documents/{documentId}
Requires Auth?
Yes. See the Getting Started page for more details.
Response Codes
| Response Code | Meaning |
|---|---|
204 | Successful deletion of doc |
404 | Document not found |