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.

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.

castrkey_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

curl https://developers.castr.io/apiv1/user/profile \\
-H "x-api-key:<your_api_key>"

curl https://developers.castr.io/apiv1/user/profile?apiKey=<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.

200 - OK	request was successfull
400 - Bad Request	request was unacceptable due to invalid or incomplete params
401 - Unauthorized	invalid or no API key specified
403 - Forbidden	API Key is not privileged to process this request
404 - Not Found	Could not find requested resource
409 - Conflict	Another 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.

POST

/apiv1/streams/create

GET

/apiv1/streams

GET

/apiv1/streams/type/<stream_type>

GET

 /apiv1/streams/<stream_id>

GET

/apiv1/streams/<stream_id>/media-stats

GET

 /apiv1/streams/<stream_id>/ingest

PATCH

 /apiv1/streams/<stream_id>/enable

PATCH

/apiv1/streams/<stream_id>/disable

DELETE

/apiv1/streams/<stream_id>

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.

{
  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.

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"
   }'

{
  "type": "live" | "restream" | "ipcam" | "scheduled",
  "name": "my stream name",
  "region": "regionID"
  }

{
  "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

curl https://developers.castr.io/apiv1/streams \
  -H "x-api-key:{your_api_key}"

[{
  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

curl https://developers.castr.io/apiv1/streams/type/restream \
  -H "x-api-key:{your_api_key}"

[{
  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

curl https://developers.castr.io/apiv1/streams/ \
  -H "x-api-key:{your_api_key}"

{
  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

curl https://developers.castr.io/apiv1/streams//ingest \
  -H "x-api-key:{your_api_key}"

{"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

curl https://developers.castr.io/apiv1/streams//media-stats \
  -H "x-api-key:{your_api_key}"

{
  "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

curl --request PATCH https://developers.castr.io/apiv1/streams/enable 
  -H "x-api-key:{your_api_key}"

{
  updated: true,
  message: ''
  }

DISABLING AN ENABLED STREAM

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

response

Returns update operation info

curl --request PATCH https://developers.castr.io/apiv1/streams/disable 
  -H "x-api-key:{your_api_key}"

{
  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.

curl --request DELETE https://developers.castr.io/apiv1/streams/ \
  -H "x-api-key:{your_api_key}"

{
  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.

POST

 /apiv1/streams/<stream_id>/platforms/create

GET

/apiv1/streams/<stream_id>/platforms/<platform_id>/ingest

PATCH

/apiv1/streams/<stream_id>/platforms/<platform_id>/ingest

PATCH

/apiv1/streams/<stream_id>/platforms/<platform_id>/enable

PATCH

/apiv1/streams/<stream_id>/platforms/<platform_id>/disable

DELETE

/apiv1/streams/<stream_id>/platforms/<platform_id>

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

{
  "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.

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
  }'

{"template":"youtube","rtmpServer":"rtmp:\/\/a.rtmp.youtube.com\/live2","streamKey":"streamkey-xxx-xxxx-xxxx","enabled":true}

{
  "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

curl https://developers.castr.io/apiv1/streams//platforms//ingest \
  -H "x-api-key:{your_api_key}"

{"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

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"
  }'

{"rtmpServer":"rtmp:\/\/rtmp-server.net\/pub\/","streamKey":"updated_key_doij18mla132"}

{"updated":true,"message":""}

ENABLING A STREAM PLATFORM

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

response

Returns update operation info

curl --request PATCH https://developers.castr.io/apiv1/streams//platforms//enable \
  -H "x-api-key:{your_api_key}"

{"updated":true,"message":""}

DISABLING A STREAM PLATFORM

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

response

Returns update operation info

curl --request PATCH https://developers.castr.io/apiv1/streams//platforms//disable \
  -H "x-api-key:{your_api_key}"

{"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

curl --request DELETE https://developers.castr.io/apiv1/streams/platforms/ \
  -H "x-api-key:{your_api_key}"

{"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.

GET

/apiv1/user/profile

PATCH

/apiv1/user/profile

GET

 /apiv1/user/subscriptions

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

{"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

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

{"name":"","username":"","email":""}

{"updated":false,"message":""}

GET USER SUBSCRIPTION

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

response

Returns array of Subscription object

curl https://developers.castr.io/apiv1/user/subscriptions \
  -H "x-api-key:{your_api_key}"

{
  "category" : "",
  "cstart" : "",
  "cend" : "",
  "package" : {
  "id": "",
  "name" : ""
  "category" : ""
  },
  "enabled" : ,
  "unsubscribed" : 
  }

[
  {
  "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

curl https://developers.castr.io/apiv1/user/profile \
  -H "x-api-key:{your_api_key}"

{
  "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.

GET

 /apiv1/ingests/

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.

{"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

curl https://developers.castr.io/apiv1/ingests/restream \
  -H "x-api-key:{your_api_key}"

[
  ...
  {
  "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.

GET

/apiv1/publishPlatforms/templates

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.

{"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

curl https://developers.castr.io/apiv1/publishPlatforms/templates \
  -H "x-api-key:{your_api_key}"

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

Castr API Reference

Authentication

USING AN API KEY

Errors

Attributes

errorstring

message string

status_codestring

Streams

THE STREAM OBJECT

Attributes

id String

enabled Boolean

typeStringlive | restream | ipcam | scheduled

name String

Nested Attributes

region.id String

region.name String

region.hostname String

dvrUnits Number

pullUrl String - Url

platforms StreamPlatform[]

CREATE NEW STREAM

Payload

typeStringrequired

nameStringrequired

regionStringrequired

GET USER STREAM

response

GET USER STREAMS BY STREAM TYPE

response

GET STREAM OBJECT BY STREAM ID

response

GET STREAM RTMP CONFIG BY STREAM ID

response

GET STREAM MEDIA INFO

response

ENABLING A DISABLED STREAM

response

DISABLING AN ENABLED STREAM

response

DELETE A STREAM

response

Streams Publish Platforms

THE STREAM PLATFORM OBJECT

Attributes

idString

enabled Boolean

templateString

name String

creationTime String

oauthData Region Object

Nested Attributes

oauthData.serviceChannelUrl String

oauthData.metadataobject

Nested Attributes

oauthData.metadata.title String

oauthData.metadata.description String

oauthData.metadata.gameString

CREATE A NEW STREAM PLATFORM

Payload

template StringStringStringStringrequired

rtmpServer Stringrequired

streamKey Stringrequired

enabled Booleanrequired

GET STREAM PLATFORM RTMP CONFIG

response

UPDATE RTMP CONFIG FOR A STREAM PLATFORM

Payload

rtmpServer Stringrequired

streamKeyStringrequired

response

ENABLING A STREAM PLATFORM

response

DISABLING A STREAM PLATFORM

response

DELETE A STREAM PLATFORM

response

User Account

THE USER OBJECT