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 the href sourced in a bylineDocuments array. 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
{
    "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
{
    "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
{
    "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
{
    "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

© 2024 npr