integrations.sh
← all integrations

ART19 Content API Documentation

OpenAPI apis-guru media

The ART19 Content API conforms to the .

API requests MUST use the HTTP Accept header:

Accept: application/vnd.api+json

API requests MUST be authenticated using the HTTP Authorization header:

Authorization: Token token="your-token", credential="your-credential"

General Notes

Some query parameters use unencoded [ and ] characters simply for readability. Defaults, examples, and possible values are additionally rendered in double quotes for readability. In practice, query parameters should not have quotes around the values (e.g., foo=bar is valid, not foo="bar"), and both query parameter keys and values must be percent-encoded, per the requirements in .

Rate Limiting

In order to provide a fair distribution of available resources, all API calls are subject to rate limits. If you exceed the number of API calls per minute granted to your credential, a 429 Too Many Requests error response will be returned.

In that case, a Retry-After header MAY be included in the response, describing the number of seconds after which a request can be retried.

If you run into a high number of 429 errors, please reach out to ART19 Support to adjust your rate limit.

Example

In the following example the request can be retried after waiting for 21 seconds:

HTTP/1.1 429 Too Many RequestsContent-Type: text/htmlRetry-After: 21

Pagination

Requests to collection endpoints SHOULD provide pagination parameters. Some endpoints REQUIRE pagination parameters to be provided. Whenever pagination is provided, it MUST be valid. Failing to provide pagination when it is required or providing wrong or incomplete pagination always results in a 400 Bad Request error response.

The page numbering starts with 1 and the maximum page size (if not otherwise documented on an endpoint) is 100. Pagination MUST NOT be specified if requesting a list of IDs (using an ids[] parameter).

Providing invalid values for page number or page size, as well as providing only a page number or only a page size, is considered an error. Pagination is provided like this:

page[number]=1&page[size]=25

Responses conform to the by including pagination links. Your requested page size will be carried into the pagination links.

Sorting

Requests to collection endpoints usually accept a sort parameter. Please refer to the for further details.

Relationship Linking

Currently, resources return all of their relationships, in no particular order, pursuant to how relationships should be returned . Consumers of this API MUST NOT make assumptions about the order of these collections. Even though this data is not currently paginated, consumers MUST support paginating relationships per the JSON:API specification if this data is important for their application.

Homepage
https://api.apis.guru/v2/specs/art19.com/1.0.0.json
Provider
art19.com
OpenAPI version
3.0.0
Spec (JSON)
https://api.apis.guru/v2/specs/art19.com/1.0.0/openapi.json
Spec (YAML)
https://api.apis.guru/v2/specs/art19.com/1.0.0/openapi.yaml

Tools (24)

Extracted live via the executor SDK.

  • classification.getClassifications

    Get a list of classifications

  • classification.getClassificationsId

    Get a specific classification

  • classificationInclusion.getClassificationInclusions

    Classification Inclusions connect classifications with entities like series, episodes, or campaigns, amongst others.

    In order to retrieve a set of classification inclusions, at least one of the following filter parameters must be provided. Failing to do so renders a 400 Bad Request response.

    • ids[]
    • classified_id and classified_type
    • classified_id and classification_type
    • classification_id and classified_type
  • classificationInclusion.getClassificationInclusionsId

    Get a specific classification inclusion

  • credit.getCredits

    Get a list of credits

  • credit.getCreditsId

    Get a specific credit

  • episode.getEpisodes

    One initial filter must be provided (ids, series_id, or season_id), otherwise a 400 Bad Request response will be returned. Additional filters are allowed.

    This API will only return episodes that your credential has permission to access, which may not be exclusive to your account, depending on the filter(s) being used. Be careful to filter the results as needed.

  • episode.getEpisodesId

    Get a specific episode

  • episode.getEpisodesIdNextSibling

    Get the episode released right after the specified one

  • episode.getEpisodesIdPreviousSibling

    Get the episode released right before the specified one

  • image.getImages

    An image represents a piece of artwork attached to some entity like a series, season, or episode, and is owned by an entity called the bucket. An image is also a container for several MediaAssets representing the physical files for various styles used.

    Media Asset Styles for Images

    Most media assets use square images. You may upload and use a square image, or upload an image of any shape and crop it to a square by specifying the cropping area. This area – identified by a coordinate x, y and a width & height – is the portion of the image used for all cover art. If an image has cropping defined, the cropped version of the image will be used in any regular or square style of media asset. If the original file is rectangular and does not have cropping, then the system will use a squared version of the original file with the smaller of width or height as the square size.

    The original image as uploaded into the system is always retained unmodified and available through the style original. All media asset styles except stripped-original consist of the cropped image.

    An image has media assets with the following styles:

    • original: This is the original file provided. May not be available, depending on permissions and file type.
    • stripped-original: The original file with all metadata (EXIF, XMP, PNG metadata, etc.) removed. This should be used for any application needing the original, uncropped, image.
    • regular: If the image has cropping defined, this is the cropped image. If not, this is a square version of the original.
    • thumb: A square thumbnail of the image with a size of 100x100 pixels.
    • square-400: A square version of the image with a size of 400x400 pixels.
    • square-640: A square version of the image with a size of 640x640 pixels.
    • square-888: A square version of the image with a size of 888x888 pixels.
    • square-3000: A square version of the image with a size of 3000x3000 pixels. This variant is only created if the cropped width & height are each at least 3000.
    • itunes: A square version of the image with a size of 1400x1400 pixels.

    Preferred image used in feeds

    For the main series image used in feeds, it is ideal to use the square-3000 version. If that is not available, the itunes version should be used instead.

  • image.getImagesId

    An image represents a piece of artwork attached to some entity like a series, season, or episode, and is owned by an entity called the bucket. An image is also a container for several MediaAssets representing the physical files for various styles used.

    Media Asset Styles for Images

    Most media assets use square images. You may upload and use a square image, or upload an image of any shape and crop it to a square by specifying the cropping area. This area – identified by a coordinate x, y and a width & height – is the portion of the image used for all cover art. If an image has cropping defined, the cropped version of the image will be used in any regular or square style of media asset. If the original file is rectangular and does not have cropping, then the system will use a squared version of the original file with the smaller of width or height as the square size.

    The original image as uploaded into the system is always retained unmodified and available through the style original. All media asset styles except stripped-original consist of the cropped image.

    An image has media assets with the following styles:

    • original: This is the original file provided. May not be available, depending on permissions and file type.
    • stripped-original: The original file with all metadata (EXIF, XMP, PNG metadata, etc.) removed. This should be used for any application needing the original, uncropped, image.
    • regular: If the image has cropping defined, this is the cropped image. If not, this is a square version of the original.
    • thumb: A square thumbnail of the image with a size of 100x100 pixels.
    • square-400: A square version of the image with a size of 400x400 pixels.
    • square-640: A square version of the image with a size of 640x640 pixels.
    • square-888: A square version of the image with a size of 888x888 pixels.
    • square-3000: A square version of the image with a size of 3000x3000 pixels. This variant is only created if the cropped width & height are each at least 3000.
    • itunes: A square version of the image with a size of 1400x1400 pixels.

    Preferred image used in feeds

    For the main series image used in feeds, it is ideal to use the square-3000 version. If that is not available, the itunes version should be used instead.

  • mediaAsset.getMediaAssets

    A media asset is part of a collection of assets or files representing an image or a piece of audio content like an episode or an ad. Images, for example, have differently sized versions for better rendering performance, and a piece of audio content usually comes in different encoding formats.

    The style attribute of a media asset describes the role an asset plays in the context of the collection. The collection is what an asset is attached to (attachment_id|type).

    Styles for Images

    Most media assets use square images. You may upload and use a square image, or upload an image of any shape and crop it to a square by specifying the cropping area. This area – identified by a coordinate x, y and a width & height – is the portion of the image used for all cover art. If an image has cropping defined, the cropped version of the image will be used in any regular or square style of media asset. If the original file is rectangular and does not have cropping, then the system will use a squared version of the original file with the smaller of width or height as the square size.

    The original image as uploaded into the system is always retained unmodified and available through the style original. All media asset styles except stripped-original consist of the cropped image.

    An image has media assets with the following styles:

    • original: This is the original file provided. May not be available, depending on permissions and file type.
    • stripped-original: The original file with all metadata (EXIF, XMP, PNG metadata, etc.) removed. This should be used for any application needing the original, uncropped, image.
    • regular: If the image has cropping defined, this is the cropped image. If not, this is a square version of the original.
    • thumb: A square thumbnail of the image with a size of 100x100 pixels.
    • square-400: A square version of the image with a size of 400x400 pixels.
    • square-640: A square version of the image with a size of 640x640 pixels.
    • square-888: A square version of the image with a size of 888x888 pixels.
    • square-3000: A square version of the image with a size of 3000x3000 pixels. This variant is only created if the cropped width & height are each at least 3000.
    • itunes: A square version of the image with a size of 1400x1400 pixels.

    Preferred image used in feeds

    For the main series image used in feeds, it is ideal to use the square-3000 version. If that is not available, the itunes version should be used instead.

    Styles for Audio

    • medium: A medium-quality version of the audio asset in various formats.
    • original: This is the original file provided. May not be available, depending on permissions and file type.
    • waveform_data: The generated BBC Audiowaveform data in JSON or binary format.
  • mediaAsset.getMediaAssetsId

    A media asset is part of a collection of assets or files representing an image or a piece of audio content like an episode or an ad. Images, for example, have differently sized versions for better rendering performance, and a piece of audio content usually comes in different encoding formats.

    The style attribute of a media asset describes the role an asset plays in the context of the collection. The collection is what an asset is attached to (attachment_id|type).

    Styles for Images

    Most media assets use square images. You may upload and use a square image, or upload an image of any shape and crop it to a square by specifying the cropping area. This area – identified by a coordinate x, y and a width & height – is the portion of the image used for all cover art. If an image has cropping defined, the cropped version of the image will be used in any regular or square style of media asset. If the original file is rectangular and does not have cropping, then the system will use a squared version of the original file with the smaller of width or height as the square size.

    The original image as uploaded into the system is always retained unmodified and available through the style original. All media asset styles except stripped-original consist of the cropped image.

    An image has media assets with the following styles:

    • original: This is the original file provided. May not be available, depending on permissions and file type.
    • stripped-original: The original file with all metadata (EXIF, XMP, PNG metadata, etc.) removed. This should be used for any application needing the original, uncropped, image.
    • regular: If the image has cropping defined, this is the cropped image. If not, this is a square version of the original.
    • thumb: A square thumbnail of the image with a size of 100x100 pixels.
    • square-400: A square version of the image with a size of 400x400 pixels.
    • square-640: A square version of the image with a size of 640x640 pixels.
    • square-888: A square version of the image with a size of 888x888 pixels.
    • square-3000: A square version of the image with a size of 3000x3000 pixels. This variant is only created if the cropped width & height are each at least 3000.
    • itunes: A square version of the image with a size of 1400x1400 pixels.

    Preferred image used in feeds

    For the main series image used in feeds, it is ideal to use the square-3000 version. If that is not available, the itunes version should be used instead.

    Styles for Audio

    • medium: A medium-quality version of the audio asset in various formats.
    • original: This is the original file provided. May not be available, depending on permissions and file type.
    • waveform_data: The generated BBC Audiowaveform data in JSON or binary format.
  • network.getNetworks

    Deprecations

    • The attribute cover_image_id has been replaced with the relationship cover_image and will be removed from the response in a future release.
  • network.getNetworksId

    Deprecations

    • The attribute cover_image_id has been replaced with the relationship cover_image and will be removed from the response in a future release.
  • person.getPeople

    Each series, season, and episode has a Credits section where you may add people and roles. This is an internal tool to recognize contributors. It is not related to ART19 users or account permissions. Each Person added will have no additional access or permissions granted as a result of being included in the Credits section.

  • person.getPeopleId

    Each series, season, and episode has a Credits section where you may add people and roles. This is an internal tool to recognize contributors. It is not related to ART19 users or account permissions. Each Person added will have no additional access or permissions granted as a result of being included in the Credits section.

  • season.getSeasons

    When retrieving a list of seasons, the result is automatically filtered depending on the privileges the used credential holds. If there are no specific privileges to a series or network, only active seasons for active series are included.

  • season.getSeasonsId

    Get a specific season

  • series.getSeries

    When retrieving a list of series, the result is automatically filtered depending on the privileges the used credential holds. All credentials will have access to active series with a public page enabled (on ART19). Utilizing a filter to limit the result to series associated with your account is recommended.

  • series.getSeriesId

    Get a specific series

  • openapi.previewSpec

    Preview an OpenAPI document before adding it as a source

  • openapi.addSource

    Add an OpenAPI source and register its operations as tools