API Overview

The Katapy API is REST-based. It accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

We are currently working on the next version of our API which will include more predictable resource-oriented URLs and support various client libraries such as Ruby, Python, PHP, Java, Kotlin, Dart, Node.js, Go, C#, Swift, Objective-C, Typescript and more.


Authentication

The Katapy API uses API keys to authenticate requests. You can request an API key from your Katapy administrator.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password.

If you need to authenticate via bearer auth (e.g., for a cross-origin request), use -H "Authorization: Bearer :apikey" instead of -u :apikey.

All API requests must be made over HTTPS.


EXAMPLE REQUEST
$ curl https://extapi.katapy.com/extapi/library/ny2c \
-u 123434234325565465456:

# Note that the colon prevents curl from requesting a password.
API KEYS

A sample test API key is included in all the examples below for illustration only.

To request data from your own Katapy account, simply replace it with the API key that you have been provided with by the Katapy team.

Libraries

A library is a centralized repository for all content assets including videos, audio, images, and documents.

Libraries are secured with access control. Users and API Keys need to be authorized to access individual libraries. Access can be requested from a Katapy administrator.

A library is identified by a library code. Note that libraries are also referred to with the alias term "mediacenter".


ENDPOINTS
GET /library/:cd
GET /libraries/accountcd/:accountCd
The Library Object

  • id long

    Unique identifier of object, mostly for internal use

  • cd string

    Alphanumerical identifier of object, mostly used in API calls

  • accountCd string

    Your Katapy account code

  • idcatNm string

    Name of object

  • idcatTagline string

    Tagline of object

  • idcatShortDesc string

    Short description of object

  • imgthumb string

    Small image thumbnail

  • lrgimgthumb string

    Large image thumbnail

  • passcode string

    Optional universal access code, e.g. for providing temporary viewing access to customers

  • and more

THE LIBRARY OBJECT
Load a Library

Parameters

  • libraryCd string

    Library identifier being used in the call

CURL GET /library/:libraryCd
$ curl https://extapi.katapy.com/extapi/library/ny2c \
-u 123434234325565465456:
RESPONSE
List Libraries

Parameters

  • accountCd string

    Account identifier being used in the call

CURL GET /libraries/accountcd/:accountCd
$ curl https://extapi.katapy.com/extapi/libraries/accountcd/ny2c \
-u 123434234325565465456:
RESPONSE
Channels

Channels allow you to present live streaming media to your consumers.

Live channels allow you to stream media as events happen in real-time. They require previous configuration by your Katapy administrator.

Linear broadcast channels allow you to schedule a 24/7 TV-style linear program.


ENDPOINTS
GET /channel/cd/:cd/:libraryCd
GET /playlist/channels/:playlistCd/:libraryCd
The Channel Object

  • id long

    Unique identifier of object, mostly for internal use

  • cd string

    Alphanumerical identifier of object, mostly used in API calls

  • accountCd string

    Your Katapy account code

  • typeCd string

    Indicator whether it is a live broadcast channel (LIVE) or a 24/7 linear channel (TV). Can be LIVE or TV.

  • idcatNm string

    Name of object

  • idcatTagline string

    Tagline of object

  • idcatShortDesc string

    Short description of object

  • imgthumb string

    Small image thumbnail

  • lrgimgthumb string

    Large image thumbnail

  • url string

    HLS streaming URL

  • url2 string

    Alternative streaming URL

  • url3 string

    Alternative streaming URL

  • testurl string

    Streaming URL for testing

  • playingflg char

    Indicator on whether the channel is currently streaming. Can be Y (Yes) or N (No).

  • nextLiveT date

    Start date in UTC of the next upcoming live broadcast event for this channel. E.g. 06/26/2020 21:42:33

  • and more

THE CHANNEL OBJECT
Load a Channel

Parameters

  • cd string

    Channel identifier being used in the call

  • libraryCd string

    Library identifier being used in the call

CURL GET /channel/cd/:cd/:libraryCd
$ curl https://extapi.katapy.com/extapi/channel/cd/ny2clive/ny2clive \
-u 123434234325565465456:
RESPONSE
List Channels

Parameters

  • playlistCd string

    Playlist identifier being used in the call

  • libraryCd string

    Library identifier being used in the call

CURL GET /playlist/channels/:playlistCd/:libraryCd
$ curl https://extapi.katapy.com/extapi/playlist/channels/livetv/lawcrime \
-u 123434234325565465456:
RESPONSE
Galleries

Galleries allow you to organize your content assets in a multi-level hierarchy of folders, sub-folders and media galleries within a library. This resembles the way a file system organizes files. Media galleries can be setup for videos, audio, images and documents.

Additionally, episodic content can be organized in series and seasons.

In most cases, content gets initially uploaded into the library's inbox. From there, users can move content around within their gallery structure of choice.


ENDPOINTS
GET /gallery/cd/:cd/:libraryCd
GET /galleries/:type/:libraryCd
GET /galleriesbyfolder/:folderCd/:libraryCd
GET /galleriesbyindex/library/:libraryCd?field=:field&value=:value
List Galleries by Type

Parameters

  • type string

    Type code being used in the call. Can be folder, video, image, document.

  • libraryCd string

    Library identifier being used in the call

CURL GET /galleries/:type/:libraryCd
$ curl https://extapi.katapy.com/extapi/galleries/video/ny2c \
-u 123434234325565465456:
RESPONSE
List Galleries by Folder

Parameters

  • folderCd string

    Folder identifier being used in the call

  • libraryCd string

    Library identifier being used in the call

CURL GET /galleriesbyfolder/:folderCd/:libraryCd
$ curl https://extapi.katapy.com/extapi/galleriesbyfolder/tourism/ny2c \
-u 123434234325565465456:
RESPONSE
List Galleries by Tag

Parameters

  • field string

    Name of the tagging field being used in the call. Can be categories, genres, actors, writers, directors, production, sponsors, owners, products, seokeys.

  • value string

    Tag value used in the call

  • libraryCd string

    Library identifier being used in the call

CURL GET /galleriesbyindex/library/:libraryCd?field=:field&value=:value
$ curl https://extapi.katapy.com/extapi/galleriesbyindex/library/ny2c?field=categories&value=Museums \
-u 123434234325565465456:
RESPONSE
Playlists

Playlists allow to curate different selections of content. The user controls the order of the selected content assets.


ENDPOINTS
GET /playlist/cd/:cd/:libraryCd
GET /playlistsbyfolder/:folderCd/:libraryCd
The Playlist Object

  • id long

    Unique identifier of object, mostly for internal use

  • cd string

    Alphanumerical identifier of object, mostly used in API calls

  • nm string

    Name of object

  • tagline string

    Tagline of object

  • shortDesc string

    Short description of object

  • imgthumb string

    Small image thumbnail

  • lrgimgthumb string

    Large image thumbnail

  • clickurl string

    HTTP link

  • seqId short

    Sequence number to custom ordering of playlists within a folder

  • mediactrCd string

    Library identifier

  • and more

THE PLAYLIST OBJECT
Load a Playlist

Parameters

  • cd string

    Playlist identifier being used in the call

  • libraryCd string

    Library identifier being used in the call

CURL GET /playlist/cd/:cd/:libraryCd
$ curl https://extapi.katapy.com/extapi/playlist/cd/homepagepromos/ny2ccms \
-u 123434234325565465456:
RESPONSE
Load Playlists

tbd


Content

Content objects contain all the metadata for your individial content assets, including encoding status and art work.

When you upload new content, a new metadata record automatically gets created and the encoding process gets initiated. Uploaded files get encoded for optimal playout, and image thumbnails are generated. After every step of the process, the content object gets updated with the latest available status information.

Content metadata can also be curated before the physical files are ready for upload. In this case match the :cd identifier with the filename without extension to automatically associate the file later.


ENDPOINTS
GET /content/cd/:cd/:libraryCd
GET /playlist/contents/:playlistCd/:libraryCd
GET /contents/:galleryCd/:libraryCd
GET /contentsbyindex/library/:libraryCd?field=:field&value=:value
The Content Object

  • id long

    Unique identifier of object, mostly for internal use

  • cd string

    Alphanumerical identifier of object, mostly used in API calls

  • nm string

    Name of object

  • tagline string

    Tagline of object

  • shortDesc string

    Short description of object

  • duration date/time

    Video duration

  • imgthumb string

    Small image thumbnail

  • lrgimgthumb string

    Large image thumbnail

  • imgthumbalt1 string

    Small image thumbnail for portrait mode

  • lrgimgthumbalt1 string

    Large image thumbnail for portrait mode

  • clickurl string

    HTTP link

  • seqId short

    Sequence number to custom ordering of content within a gallery

  • mediactrCd string

    Library identifier

  • catCd string

    Gallery identifier

  • catNm string

    Gallery name

  • folderCd string

    Folder identifier

  • folderNm string

    Folder name

  • viewscount int

    Total views since published in Katapy, for ordering for popular content

  • mediatypeNm int

    Media type such as Video, Image, Document, Audio

  • detailsclobId long

    Unique identifier of the content's long description, which can be in HTML format

  • publishflg char

    Indicator to show whether the content is published or not. Can be Y (Yes) or N (No).

  • privateflg char

    Indicator to show whether the content is private or not. Can be Y (Yes) or N (No).

  • seokeys string

    SEO keys

  • seodesc string

    SEO description

  • darx int

    Display Aspect Ratio X

  • dary int

    Display Aspect Ratio Y

  • network string

    Network

  • artist string

    List of artists

  • productionT date

    Production Date

  • author string

    Author

  • episodeNum small

    Episode #

  • seasonNum string

    Season #

  • actors string

    Comma delimited list of actors

  • writers string

    Comma delimited list of writers

  • directors string

    Comma delimited list of directors

  • production string

    Comma delimited list of producers or production companies

  • genres string

    Comma delimited list of genres

  • categories string

    Comma delimited list of categories

  • runtime int

    Runtime in minutes

  • popularity float

    Popularity in decimal number

  • imgUrl string

    URL for video poster

  • hlsUrl string

    URL for LD HLS stream (HTTP Live Streaming). To get URLs for higher def, add URL parameter device=SD to URL request

  • hdsUrl string

    URL for LD HDS stream (HTTP Dynamic Streaming). To get URLs for higher def, add URL parameter device=SD to URL request

  • rtmpUrl string

    URL for RTMP stream (Real Time Messaging Protocol)

  • smilUrl string

    SMIL file URL for adaptive RTML streaming

  • hlsaUrl string

    HLS URL for adaptive HLS streaming

  • hdsaUrl string

    HDS url for adaptive HDS streaming

  • srtUrl string

    SRT URL for closed captioning support

  • and more

THE CONTENT OBJECT
Load a Content

Parameters

  • cd string

    Content identifier being used in the call

  • libraryCd string

    Library identifier being used in the call

CURL GET /content/cd/:cd/:libraryCd
$ curl https://extapi.katapy.com/extapi/content/cd/grandcentralterminal/ny2c \
-u 123434234325565465456:
RESPONSE
List Content by Playlist

Parameters

  • cd string

    Playlist identifier being used in the call

  • libraryCd string

    Library identifier being used in the call

CURL GET /playlist/contents/:playlistCd/:libraryCd
$ curl https://extapi.katapy.com/extapi/playlist/contents/homepagepromos/ny2ccms \
-u 123434234325565465456:
RESPONSE
List Content by Gallery

Parameters

  • galleryCd string

    Folder identifier being used in the call

  • libraryCd string

    Library identifier being used in the call

CURL GET /galleriesbyfolder/:galleryCd/:libraryCd
$ curl https://extapi.katapy.com/extapi/contents/visitorsites/ny2c \
-u 123434234325565465456:
RESPONSE
List Content by Tag

Parameters

  • field string

    Name of the tagging field being used in the call. Can be categories, genres, actors, writers, directors, production, sponsors, owners, products, seokeys.

  • value string

    Tag value used in the call

  • libraryCd string

    Library identifier being used in the call

CURL GET /contentsbyindex/library/:libraryCd?field=:field&value=:value
$ curl https://extapi.katapy.com/extapi/contentsbyindex/library/ny2c?field=categories&value=Museums \
-u 123434234325565465456:
RESPONSE

Linear Schedule

tbd


Live Events

tbd