GET profile
Get an individual CDS Profile. The list of valid CDS profiles can be found here
GET /v1/profiles/{profileName}
Requires Auth?
No (open access)
Response Codes
| Response Code | Meaning |
|---|---|
200 | A single CDS Schema or Profile in JSON format |
{
"$schema": "https://json-schema.org/draft/2019-09/schema#",
"$id": "/v1/profiles/youtube-video",
"title": "YouTube Video",
"description": "An asset representing a YouTube video associated with a document. For more information on how to use this to construct a link/embed, see https://developers.google.com/youtube.",
"type": "object",
"required": [
"videoId"
],
"properties": {
"headline": {
"description": "The person, organization, or series associated with this video for attribution purposes",
"type": "string"
},
"subheadline": {
"description": "The caption used for the embedded video link",
"type": "string"
},
"startTime": {
"description": "Number of seconds in the video to start playback",
"type": "integer",
"minimum": 0
},
"videoId": {
"description": "The ID used to identify this video within YouTube's API.",
"type": "string",
"pattern": "^[^ ]+$"
},
"embedSize": {
"description": "The relative size the embedded YouTube player should be displayed at",
"type": "string",
"enum": [
"small",
"medium",
"large",
"x-large"
]
}
}
}
404 | CDS Schema or Profile not found |
GET All Profiles
Get a list of all current CDS profiles. More information can be found here.
GET /v1/profiles
Requires Auth?
No (open access)
Response Codes
| Response Code | Meaning |
|---|---|
200 | Successfully returned list of CDS profiles in JSON format |
[
{
"href": "/v1/profiles/aggregation"
},
{
"href": "/v1/profiles/audio-card"
},
{
"href": "/v1/profiles/audio"
}
...
]
GET Schema
Get an individual CDS JSON Schema
GET /v1/schemas/{schemaName}
Requires Auth?
No (open access)
Response Codes
| Response Code | Meaning |
|---|---|
200 | Successfully returned list of CDS profiles in JSON format |
{
"$schema": "https://json-schema.org/draft/2019-09/schema#",
"$id": "/v1/schemas/link",
"title": "Link",
"description": "A link to an externally-defined location",
"type": "object",
"required": [
"href"
],
"properties": {
"href": {
"description": "An RFC3987-compliant internationalized URI",
"type": "string",
"format": "iri-reference"
},
"rels": {
"description": "An array of RFC8288-compliant link relation types",
"type": "array",
"uniqueItems": true,
"items": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "string",
"pattern": "^[a-z][a-z0-9.-]*$"
}
]
}
},
"embed": {
"description": "This attribute will be used to hold pre-fetched content from this link. If this attribute is present, it should be interpreted as the unaltered response from the link specified in the 'href' attribute.",
"readOnly": true
}
}
}
400 | Bad request |
{
"meta": {
"messages": [
"Failed to load schema: nonExistentSchemaName.json"
]
}
}
404 | Schema not found |
GET Client Profile
Retrieve a single client profile from CDS by name.
GET /v1/client-profiles/{profileName}
Requires Authorization Token?
No, it can be queried directly as a GET request. Example https://content.api.npr.org/v1/client-profiles/
Responses
200 - Success
On a successful retrieval, a 200 response code will be returned. The body of the response will be the JSON schema respresnting the client profile.
Example:
GET https://content.api.npr.org/v1/client-profiles/example-profile
---
200
{
"$schema": "https://json-schema.org/draft/2019-09/schema#",
"$id": "/v1/client-profiles/example-profile",
"title": "Example Profile",
"type": "object",
"required": [
...
}
404 - Profile not found
If the requested client profile does not exist, a 404 status code will be returned with an error response.
GET https://content.api.npr.org/v1/client-profiles/invalid-profile
---
404
{
"meta": {
"messages": [
"Failed to load profile invalid-profile"
]
}
}
GET Query Client Profiles
Retrieve a set of client profiles from CDS
GET /v1/client-profiles
Requires Authorization Token?
No, it can be queried directly as a GET request. Example https://content.api.npr.org/v1/client-profiles/
Query Parameters
This endpoint supports two query parameters:
| Name | Minumum | Maximum | Default | Description |
|---|---|---|---|---|
limit | 1 | 300 | 20 | How many profiles to return |
offset | 0 | (2000 - limit) | 0 | Where to begin the return set of profiles |
limit and offset allow for a simple method of paginating through client profiles when searching for them. Together, these values cannot add up to more than 2000.
Responses
200 - Success
On a successful retrieval, a 200 response code will be returned. The body of the response will be the profiles in a JSON content view.
Example:
GET https://content.api.npr.org/v1/client-profiles?offset=0&limit=20
---
200
{
"resources": [
{
"$schema": "https://json-schema.org/draft/2019-09/schema#",
"$id": "/v1/client-profiles/example-profile",
"title": "Example Profile",
"type": "object",
"required": [
...
},
...
]
}
400 - Invalid request
If one or more of the query parameters given is invalid, a 400 response will be returned with an error explanation.
GET https://content.api.npr.org/v1/client-profiles?limit=all-of-them
---
400
{
"meta": {
"messages": [
"all-of-them is an invalid limit value"
]
}
}