Castr API Reference

This document covers in-depth knowledge on how to use Castr. API to set out a successful integration with third-party apps. Castr API uses the REST scheme and has resource relevant endpoints, primarily uses JSON-encoded format to exchange data between client & server i.e., request body and server response.

Apps leveraging Castr API can perform numerous operations such as; stream creation, deletion, modifying publish platforms, stopping broadcasts, etc. along with getting users information and subscriptions. The Castr API is capable enough to carry out all streaming-oriented operations available in Castr Dashboard.

The Castr API, in essence, consists of public/private APIs. Private APIs are restricted access and require APIs to Authenticate with an API Key associated with each of castr account.

The Castr API is being continuously maintained but does not intend to deprecate existing endpoints but will keep on assigning new API versions with base pathnames /apiv<api_vr> as we release newer and tailored functionalities.

Base URL
https://developers.castr.io/apiv1

Authentication

The Castr API requires API key Authorization to authenticate restricted API requests such as managing streaming and account details. You can access and manage your API key in Developer Settings inside Castr Dashboard.

Please note that your API key is capable of managing most of your account on your behalf, from managing streams to retrieving account details, so be sure to keep them secure! Do not share API key in publicly accessible zones or snippets.


USING AN API KEY

To use your API key, there are two easy ways;

Either assigning API Key value to a custom HEADER in API request

x-api-key : <your_api_key>

Adding a query string param `apiKey` to API request URL directly

?apiKey=<your_api_key>

All API requests must be made over HTTPS. Therefore, any of HTTP requests will either get ignored or will fail to receive any server response ending up with a timeout error.

Castr API key Syntax
castrkey_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Header Based Authentication
curl https://developers.castr.io/apiv1/user/profile \\
-H "x-api-key:<your_api_key>"
Querystring Based Authentication
curl https://developers.castr.io/apiv1/user/profile?apiKey=<your_api_key>
Your API Key

To test requests using your account creds, replace the sample API key with your actual API key

Errors

Castr API server uses standard HTTP response codes to acknowledge about success or failure of action requests via an API request. Fundamentally, codes ranging in 200s indicates success and codes ranging in 400s and 500s indicates a failure happening either in an api request (e.g invalid request input/param/body) or server implementation(less frequent).

Attributes
  • errorstring

    The type of error returned. This gives an idea of the what exactly has happened such as; `bad request`, `unauthorized`, `resource conflict`, `forbidden`

  • message string

    A verbose text indicating the reason(s) for why the request couldn't fulfilled

  • status_codestring

    Returned HTTP status code relevant to the request failure Note: Even though the server will respond with a proper HTTP status code. This property will still hold the same HTTP status code value for code reference.

HTTP status code summary
200 - OK request was successfull
400 - Bad Requestrequest was unacceptable due to invalid or incomplete params
401 - Unauthorizedinvalid or no API key specified
403 - ForbiddenAPI Key is not privileged to process this request
404 - Not FoundCould not find requested resource
409 - ConflictAnother resource exists with similar attribute
500 - 505 - Server Errors Something expected happened

Streams

Castr API covers all essential actions associated with managing users Streams and Broadcasts such as; stream creation / updation / deletion /enabling / disabling / ingestion etc.

Castr supports different kinds of streams each relating their relevant specs and listed below;

restream  For simulcasting/restreaming content to different streaming websites/platforms
live  For Livestreaming broadcasts featuring customizable Player embeds, cloud recording, security features and more
ipcam  For IPCamera ingestion/restreaming with cloud recording enabled
scheduled  For simulcasting but with pre-recorded and not ingestion

Note: each type of stream requires deployment onto their supported regions according to the type specified.

THE STREAM OBJECT

Attributes
  • id String

    String representing the id of a stream object.

  • enabled Boolean

    Boolean representing whether the Stream is enabled or disabled.

  • typeStringlive | restream | ipcam | scheduled

    String representing the type of stream user had deployed.

  • name String

    String representing the name of the stream appearing on the dashboard. Stream names are changeable.

    Nested Attributes
    • region.id String

      String representing id of the region object.

    • region.name String

      String representing the name of the region.

    • region.hostname String

      String representing DNS hostname for the server ingests.

  • dvrUnits Number

    Number representing the number of units assigned for cloud recording.

  • pullUrl String - Url

    String representing the media(RTMP/M3u8..) URL to be used as pull source for the stream

  • platforms StreamPlatform[]

    Array representing the list of StreamPlatform objects attached to a stream.

The Stream object
{
  id: 'md09j1wim[aksd',
  enabled: false,
  type: 'live',
  name: 'dj youtube 19k',
  region: {
    id: "pok27dmlaksdk",
    name: "Chicago, US",
    hostname: "us-central.castr.io",
  },
  dvrUnits: 4,
  pullUrl: null,
  platforms: []
}

CREATE NEW STREAM

Payload
  • typeStringrequired

    String representing the type of the stream to be deployed. Value must be one of the following; `live`, `restream`, `ipcam`, `scheduled`.

  • nameStringrequired

    String representing the name of the stream appearing on the dashboard. Stream names are changeable.

  • regionStringrequired

    String representing id of the selected deployment region. Note: selection and availability of streaming regions are determined by the type of the stream to be deployed i.e., live/restream/ipcam/scheduled. Please find the list of regions by type here.

POST
/apiv1/streams/create
curl --request POST https://developers.castr.io/apiv1/streams/create \
  -H "Content-Type: application/json" \
  -H "x-api-key:{your_api_key}" \
  -d '{
    "type": "live",
    "name": "my stream name",
    "region": "5bc02ca183c5d1f2016d6d4c"
   }'
REQUEST BODY
{
  "type": "live" | "restream" | "ipcam" | "scheduled",
  "name": "my stream name",
  "region": "regionID"
  }
RESPONSE
{
  "id": 'md09j1wim[aksd',
  "enabled": false,
  "type": 'live',
  "name": 'dj youtube 19k',
  "region": {
  "id": "pok27dmlaksdk",
  "name": "Chicago, US",
  "hostname": "us-central.castr.io",
  },
  "dvrUnits": 4,
  "pullUrl": null,
  "platforms": []
  }

GET USER STREAM

Get list of streams associated to an account

response

Returns array of Stream object

GET
/apiv1/streams
curl https://developers.castr.io/apiv1/streams \
  -H "x-api-key:{your_api_key}"
RESPONSE
[{
  id: 'md09j1wim[aksd',
  enabled: false,
  type: 'live',
  name: 'dj youtube 19k',
  region: {
  id: "pok27dmlaksdk",
  name: "Chicago, US",
  hostname: "us-central.castr.io",
  },
  dvrUnits: 4,
  pullUrl: null,
  platforms: []
  }, {
  id: 'dio1mwdpmf3',
  enabled: true,
  type: 'restream',
  name: 'twitch_simulcast',
  region: {
  id: "pok27dmlaksdk",
  name: "Singapore",
  hostname: "sg.castr.io",
  },
  dvrUnits: 0,
  pullUrl: "https://example.com/root/some_media/index.m3u8",
  platforms: []
  }]

GET USER STREAMS BY STREAM TYPE

Get a list of streams associated with an account but filtered by stream type specified.

response

Returns Array of Stream objects

GET
/apiv1/streams/type/<stream_type>
curl https://developers.castr.io/apiv1/streams/type/restream \
  -H "x-api-key:{your_api_key}"
RESPONSE
[{
  id: 'dio1mwdpmf3',
  enabled: true,
  type: 'restream',
  name: 'twitch_simulcast',
  region: {
  id: "pok27dmlaksdk",
  name: "Singapore",
  hostname: "sg.castr.io",
  },
  dvrUnits: 0,
  pullUrl: null,
  platforms: []
  }]

GET STREAM OBJECT BY STREAM ID

Get Stream details by Stream id specified.
Note: stream key is different from stream id.

response

Returns Stream object

GET
/apiv1/streams/<stream_id>
curl https://developers.castr.io/apiv1/streams/ \
  -H "x-api-key:{your_api_key}"
RESPONSE
{
  id: 'dio1mwdpmf3',
  enabled: true,
  type: 'restream',
  name: 'twitch_simulcast',
  region: {
  id: "pok27dmlaksdk",
  name: "Singapore",
  hostname: "sg.castr.io",
  },
  dvrUnits: 0,
  pullUrl: null,
  platforms: []
  }

GET STREAM RTMP CONFIG BY STREAM ID

Get RTMP ingests/config, including ingest server address and stream key.

response

Returns Stream ingestion/rtmp config

GET
/apiv1/streams/<stream_id>/ingest
curl https://developers.castr.io/apiv1/streams//ingest \
  -H "x-api-key:{your_api_key}"
RESPONSE
{"rtmpServer":"rtmp:\/\/ny.castr.io","streamKey":"livem91j9a2kckomas"}

GET STREAM MEDIA INFO

Get media information for a stream, including stream status/health, uptime, video resolution, codec information, bitrates, etc.

response

Returns Stream Media Info Object

GET
/apiv1/streams/<stream_id>/media-stats
curl https://developers.castr.io/apiv1/streams//media-stats \
  -H "x-api-key:{your_api_key}"
RESPONSE
{
  "push_stats": {
  "rtmp://example-rtmp-server.net:1935/some_stream/my_streamkey?q=md10j": 21077838799,
  },
  "alive": true,
  "bitrate": 2008,
  "codecs": [
  {
    "type": "audio",
    "codec": "aac"
  },
  {
    "type": "video",
    "codec": "h264"
  }
  ],
  "width": 1920,
  "height": 1080,
  "fps": 25
  }

ENABLING A DISABLED STREAM

Change stream status to `enabled` for an already disabled stream.

response

Returns update operation info

PATCH
/apiv1/streams/<stream_id>/enable
curl --request PATCH https://developers.castr.io/apiv1/streams/enable 
  -H "x-api-key:{your_api_key}"
RESPONSE
{
  updated: true,
  message: ''
  }

DISABLING AN ENABLED STREAM

Change stream status to `disabled` for an enabled stream.

response

Returns update operation info

PATCH
/apiv1/streams/<stream_id>/disable
curl --request PATCH https://developers.castr.io/apiv1/streams/disable 
  -H "x-api-key:{your_api_key}"
RESPONSE
{
  updated: true,
  message: ''
  }

DELETE A STREAM

Delete a stream with all of its data (recordings, players, settings, etc.)

response

Returns deleted stream object and removal operation info.

DELETE
/apiv1/streams/<stream_id>
curl --request DELETE https://developers.castr.io/apiv1/streams/ \
  -H "x-api-key:{your_api_key}"
RESPONSE
{
  removed: true,
  stream: {
    id: 'dio1mwdpmf3',
    enabled: true,
    type: 'restream',
    name: 'twitch_simulcast',
    region: {
      id: "pok27dmlaksdk",
      name: "Singapore",
      hostname: "sg.castr.io",
    },
    dvrUnits: 0,
    pullUrl: null,
    platforms: []
    }
  }

Streams Publish Platforms

This section covers managing Publish Platforms (publish destinations) for a stream with all essential actions available in Castr Dashboard.

A Publish platform requires a publish template to be used as a base platform definition
See PublishTemplate for more details.

THE STREAM PLATFORM OBJECT

Attributes
  • idString

    String representing the id of the stream platform

  • enabled Boolean

    Boolean representing whether the platform is enabled to be pushed when stream is live

  • templateString

    String representing the name/template of the PublishTemplate from predefined list of templates. To learn more, checkout our list of supported Publish Templates

  • name String

    String representing the name of the platform appearing on the dashboard. Platform names do not contribute in streaming and are solely for classification purposes

  • creationTime String

    String representing the ISO timestamp for the time platform was originaly attached to stream.

  • oauthData Region Object

    For platforms that had linked with external streaming websites like Facebook, Youtube, Mixer etc directly from Castr dashboard

    Nested Attributes
    • oauthData.serviceChannelUrl String

      String representing users' web channel/profile url hosted on the linked streaming website

    • oauthData.metadataobject

      Plain object containing stream metadata for linked streaming website

      Nested Attributes
      • oauthData.metadata.title String

        String representing the `title` to be used for broadcast streamed onto linked streaming website

      • oauthData.metadata.description String

        String representing the `description` to be used for broadcast streamed onto linked streaming website

      • oauthData.metadata.gameString

        String representing the name of the `game` to be used for broadcasts on twitch streaming platform

The Stream Platform Object
{
  "id": "dai7jhs61",
  "enabled": true,
  "name": "MY YT VLOG",
  "template": "youtube",
  "creationTime": "2019-10-31T18:01:10.331Z"
  "oauthData": {
    "serviceChannelUrl": "https://youtube.com/mychannel",
    "metadata": {
      "title": "streaming title",
      "description": "streaming text/html description",
    }
  }
}

CREATE A NEW STREAM PLATFORM

Creates and attach a new Publish platform to a stream

Payload
  • template StringStringStringStringrequired

    String representing the name/template of the PublishTemplate to be used from predefined templates. To learn more, checkout our list of supported Publish Templates.

  • rtmpServer Stringrequired

    String representing the RTMP ingest/server address but without stream key.

  • streamKey Stringrequired

    String representing the stream key for the provided RTMP server.

  • enabled Booleanrequired

    Boolean indicating if the new platform should be enabled(toggled) by default, so castr will begin pushing data to the new Publish platform as soon as the relevant stream becomes online.

POST
/apiv1/streams/<stream_id>/platforms/create
curl --request POST https://developers.castr.io/apiv1/streams/platforms/create \
  -H "Content-Type: application/json"
  -H "x-api-key:{your_api_key}" \
  -d '{
    "template": "youtube",
    "rtmpServer": "rtmp://a.rtmp.youtube.com/live2",
    "streamKey": "streamkey-xxx-xxxx-xxxx",
    "enabled": true
  }'
REQUEST BODY
{"template":"youtube","rtmpServer":"rtmp:\/\/a.rtmp.youtube.com\/live2","streamKey":"streamkey-xxx-xxxx-xxxx","enabled":true}
RESPONSE
{
  "id": "asdjynoiynd",
  "name": "youtube_2",
  "template": "youtube",
  "rtmpServer": "rtmp://a.rtmp.youtube.com/live2",
  "streamKey": "streamkey-xxx-xxxx-xxxx",
  "enabled": true,
  }

GET STREAM PLATFORM RTMP CONFIG

Get RTMP ingests/config for a Publish platform.

response

Returns stream platform ingestion/rtmp config

GET
/apiv1/streams/<stream_id>/platforms/<platform_id>/ingest
curl https://developers.castr.io/apiv1/streams//platforms//ingest \
  -H "x-api-key:{your_api_key}"
RESPONSE
{"rtmpServer":"rtmp:\/\/a.rtmp.youtube.com\/live2","streamKey":"streamkey-xxx-xxxx-xxxx"}

UPDATE RTMP CONFIG FOR A STREAM PLATFORM

Payload
  • rtmpServer Stringrequired

    String representing the RTMP ingest/server address but without stream key.

  • streamKeyStringrequired

    String representing the stream key for the provided RTMP server.

response

Returns update operation info

PATCH
/apiv1/streams//platforms/<platform_id>/ingest
curl --request PATCH https://developers.castr.io/apiv1/streams//platforms/<platform_id>/ingest \
  -H "x-api-key:{your_api_key}" \
  -d '{
    "rtmpServer": "rtmp://rtmp-server.net/pub/",
    "streamKey": "updated_key_doij18mla132"
  }'
REQUEST BODY
{"rtmpServer":"rtmp:\/\/rtmp-server.net\/pub\/","streamKey":"updated_key_doij18mla132"}
RESPONSE
{"updated":true,"message":""}

ENABLING A STREAM PLATFORM

Changes stream status to `enabled` for a disabled stream platform.

response

Returns update operation info

PATCH
/apiv1/streams/<stream_id>/platforms/<platform_id>/enable
curl --request PATCH https://developers.castr.io/apiv1/streams//platforms//enable \
  -H "x-api-key:{your_api_key}"
RESPONSE
{"updated":true,"message":""}

DISABLING A STREAM PLATFORM

Changes stream status to `disabled` for an enabled stream platform.

response

Returns update operation info

/apiv1/streams//platforms/<platform_id>/disable
curl --request PATCH https://developers.castr.io/apiv1/streams//platforms//disable \
  -H "x-api-key:{your_api_key}"
RESPONSE
{"updated":true,"message":""}

DELETE A STREAM PLATFORM

Unlinks and deletes a Publish platform from a stream.

response

Returns deleted stream platform object and removal operation info

DELETE
/apiv1/streams//platforms/<platform_id>
curl --request DELETE https://developers.castr.io/apiv1/streams/platforms/ \
  -H "x-api-key:{your_api_key}"
RESPONSE
{"removed":true,"platform":{"id":"5b8odnqwns","enabled":false,"name":"_mixer GTA{V}","template":"mixer","creationTime":"2019-10-31T18:01:10.331Z"}}

User Account

This section covers APIs required to retrieve user/customer information, including basic profile information and the list of Castr Subscriptions the user has/had subscribed for.

Note: each type of stream requires deployment onto their supported regions according to the type specified.

Note: Castr APIs hold a limited scope of User Accounts APIs mainly for retrieving user data and prefers to leverage Castr Dashboard for managing user sensitive data such as subscriptions and payments for security measures.

THE USER OBJECT

Attributes
  • id String

    String representing the id of the customer/user account

  • enabledBoolean

    Boolean representing if the user account is active or suspended

  • nameString

    String representing the name of the customer/user account

  • emailString

    String representing primary email address associated with account

  • usernameString

    String representing the username (account alias) of a user. Note: username can also be used as an alias to email address while logging into the app

  • phoneString

    String representing phone number the user had initially signed-up with

  • joinDateString

    String representing the ISO timestamp for user signup time

The User object
{"id":"5d1af416fadbfc17e7c17d4a","enabled":true,"name":"John McDonald","email":"[email protected]","phone":"+447722129965","username":"john5dwr6","joinDate":"2019-07-02T06:05:10.383Z"}

UPDATE USER PROFILE

Updates only a chunk of user profile information.

Payload
  • name Stringoptional

    account name to be updated.

  • username Stringoptional

    username to be updated. Note: a username already occupied in the system will not be allowed and will get ignored.

  • email Stringoptional

    email address to be updated.

response

Returns update operation info

PATCH
/apiv1/user/profile
curl --request PATCH https://developers.castr.io/apiv1/user/profile \
  -H "x-api-key:{your_api_key}"  \
  -d '{
    "name": "",
    "username": "",
    "email": ""
  }'
REQUEST BODY
{"name":"","username":"","email":""}
RESPONSE
{"updated":false,"message":""}

GET USER SUBSCRIPTION

Gets a list of subscription objects associated with customer/user account.

response

Returns array of Subscription object

GET
/apiv1/user/subscriptions
curl https://developers.castr.io/apiv1/user/subscriptions \
  -H "x-api-key:{your_api_key}"
The Subscription Object
{
  "category" : "",
  "cstart" : "",
  "cend" : "",
  "package" : {
  "id": "",
  "name" : ""
  "category" : ""
  },
  "enabled" : ,
  "unsubscribed" : 
  }
RESPONSE
[
  {
  "category": "restream",
  "cstart" : "2019-06-15T22:00:00Z",
  "cend" : "2019-07-14T00:00:00Z",
  "package" : {
    "id": "5d03972956a0e43c9eb21e8d",
    "name" : "Broadcast X2",
    category: "restream"
  },
  "enabled" : false,
  "unsubscribed" : false
  },
  {
  "category": "live",
  "cstart" : "2019-07-02T13:04:24Z",
  "cend" : "2020-06-29T00:00:00Z",
  "package" : {
    "id": "5d03972956a0e43c9eb21e8d",
    "name" : "2TB Bandwidth - Yearly",
    "category" : "live"
  },
  "enabled" : true,
  "unsubscribed" : false
  }
  ]

GET USER PROFILE

Gets information on user profile.

response

Returns UserProfile object

GET
/apiv1/user/profile
curl https://developers.castr.io/apiv1/user/profile \
  -H "x-api-key:{your_api_key}"
RESPONSE
{
  "id" : "5d1af416fadbfc17e7c17d4a",
  "enabled" : true,
  "name" : "John McDonald",
  "email" : "[email protected]",
  "phone" : "+447722129965",
  "username" : "john5dwr6",
  "joinDate" : ISODate("2019-07-02T06:05:10.383Z")
  }

Deployment Region

Regions or Deployment Regions are used to specify deployment location for a given stream, letting Castr know where to create and listed for your stream ingests.

When creating a new stream, one can use the region list API with the given stream type to list out available deployment regions for the same category associated with the specified user account. Different users can be given a different list of regions depending upon their subscriptions.

Note: Regions are categorized according to the stream type they support (e.g. `live`, `restream`, `ipcam`, `scheduled`). For instance, Region for `live` category can not be used to deploy a stream of `restream` type.

Endpoints

THE REGION OBJECT

Attributes
  • id String

    String representing the id of the region.

  • nameString

    String representing the name of the region.

  • hostnameString

    String representing ingest server hostname of the region.

The Region object
{"id":"5d1af416fadbfc17e7c17d4a","name":"Chicago","hostname":"cg.castr.io"}

LIST AVAILABLE REGIONS BY STREAM TYPE

Gets a list of available Region objects for an account by stream type (restream | live | ipcam | scheduled).

response

Returns array of Region objects

GET
/apiv1/ingests/<stream_type>
curl https://developers.castr.io/apiv1/ingests/restream \
  -H "x-api-key:{your_api_key}"
RESPONSE
[
  ...
  {
  "id" : "5afd44bd49db36723437135",
  "name" : "Chicago US",
  "hostname" : "cg.castr.io"
  },
  {
  "id" : "5afd44bd49db36723437135b",
  "name" : "Los Angeles US",
  "hostname" : "ca.castr.io"
  },
  {
  "id" : "5b1c3dc6f5b8e43e90093338",
  "name" : "Brazil",
  "hostname" : "br.castr.io"
  }
  ...
  ]

Publish Platform Templates

Publish Platform Templates are the basis of StreamPlatforms as they define the base configuration of an RTMP ingestion attached to a stream.

Note: When creating a new stream platform, it is essential only to include a template present in the supported publish templates list.

THE PUBLISH TEMPLATE OBJECT

Attributes
  • template String

    String representing the template name of the publish service.

  • icon String

    String representing the brand logo URL for the publish service.

  • ingestionObject

    Object holding ingests definition like RTMP servers etc.

    Nested Attributes
    • ingestion.servers String[]

      An array of strings representing a list of available RTMP servers for a given publish service.

    • ingestion.streamkeySampleString

      String representing a sample of a stream key pattern supported by the given publish service.

  • oauthReady Boolean

    Boolean indicating whether a given publish service supports OAuth (service account linking) from Castr Dashboard.

The Publish Template object
{"template":"dlive","icon":"\/\/icon-url","ingestion":{"servers":["rtmp:\/\/stream.dlive.tv\/live"],"streamkeySample":"aq6U8I3Osok9d05ExWeCZ12AGy7nsjl_password"},"oauthReady":false}

LIST ALL SUPPORTED PUBLISH TEMPLATES

Gets a list of Publish platform templates currently supported by Castr.

response

Returns array of PublishTemplate objects

GET
/apiv1/publishPlatforms/templates
curl https://developers.castr.io/apiv1/publishPlatforms/templates \
  -H "x-api-key:{your_api_key}"
RESPONSE
[{"template":"dlive","icon":"\/\/icon-url","ingestion":{"servers":["rtmp:\/\/stream.dlive.tv\/live"],"streamkeySample":"aq6U8I3Osok9d05ExWeCZ12AGy7nsjl_password"},"oauthReady":false}]