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`

  • messagestring

    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 - OKrequest 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 ErrorsSomething 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
  • idString

    String representing the id of a stream object.

  • enabledBoolean

    Boolean representing whether the Stream is enabled or disabled.

  • typeString live | restream | ipcam | scheduled

    String representing the type of stream user had deployed.

  • nameString

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

  • regionRegion Object

    Plain Object containing details of the deployment region.

    Nested Attributes
    • region.idString

      String representing id of the region object.

    • region.nameString

      String representing the name of the region.

    • region.hostnameString

      String representing DNS hostname for the server ingests.

  • dvrUnitsNumber

    Number representing the number of units assigned for cloud recording.

  • pullUrlString - Url

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

  • platformsStreamPlatform[]

    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: []
}
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.

response

POST
/apiv1/streams/create
curl --request POST https://developers.castr.io/apiv1/streams/create \
  -H "x-api-key:{your_api_key}" \
  -d '{
    "type": "live",
    "name": "my stream name",
    "region": "<region_id>"
   }'
REQUEST BODY
{
  "type": "live" | "restream" | "ipcam" | "scheduled",
  "name": "my stream name",
  "region": "<region_id>"
  }
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 STREAMS

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/<stream_id> \
  -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>/ingestion
curl https://developers.castr.io/apiv1/streams/<stream_id>/ingestion \
  -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/<stream_id>/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/<stream_id>/enable \
  -H "x-api-key:{your_api_key}"
RESPONSE
{
  updated: true,
  message: '<acknowledge_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/<stream_id>/disable \
  -H "x-api-key:{your_api_key}"
RESPONSE
{
  updated: true,
  message: '<acknowledge_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/<stream_id> \
  -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

  • enabledBoolean

    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

  • nameString

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

  • creationTimeString

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

  • oauthDataRegion Object

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

    Nested Attributes
    • oauthData.serviceChannelUrlString

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

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

      • oauthData.metadata.descriptionString

        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
  • templateStringrequired

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

  • rtmpServerStringrequired

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

  • streamKeyStringrequired

    String representing the stream key for the provided RTMP server.

  • enabledBooleanrequired

    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.

response

Returns newly created StreamPlatform object

POST
/apiv1/streams/<stream_id>/platforms/create
curl --request POST https://developers.castr.io/apiv1/streams/<stream_id>/platforms/create \
  -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/<stream_id>/platforms/<platform_id>/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

Updates RTMP ingests/config for a Publish platform with RTMP credentials specified.

payload
  • rtmpServerStringrequired

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

DISABLING A STREAM PLATFORM

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

response

Returns update operation info

PATCH
/apiv1/streams/<stream_id>/platforms/<platform_id>/disable
curl --request PATCH https://developers.castr.io/apiv1/streams/<stream_id>/platforms/<platform_id>/disable \
  -H "x-api-key:{your_api_key}"
RESPONSE
{
  "updated": true,
  "message": "<acknowledge_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/<stream_id>/platforms/<platform_id>
curl --request DELETE https://developers.castr.io/apiv1/streams/<stream_id>platforms/<platform_id> \
  -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: 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
  • idString

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

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

UPDATE USER PROFILE

Updates only a chunk of user profile information.

payload
  • nameStringoptional

    account name to be updated.

  • usernameStringoptional

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

  • emailStringoptional

    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": "<updated name>",
    "username": "<updated username>",
    "email": "<updated email address>"
  }'
REQUEST BODY
{
  "name" : "<name to update>",
  "username" : "<username to update>",
  "email": "<updated email address>"
}
RESPONSE
{
  "updated" : false,
  "message" : "<acknowledge_message>"
}

GET USER SUBSCRIPTIONS

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" : "<subscription_type>",
  "cstart" : "<iso_time_string>",
  "cend" : "<iso_time_string>",
  "package" : {
  "id": "<package_id>",
  "name" : "<package_name>"
  "category" : "<subscription_type>"
  },
  "enabled" : <boolean>,
  "unsubscribed" : <boolean>
  }
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
  }
  ]

Deployment Regions

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.

The Region object

Attributes
  • idString

    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
  • templateString

    String representing the template name of the publish service.

  • iconString

    String representing the brand logo URL for the publish service.

  • ingestionObject

    Object holding ingests definition like RTMP servers etc.

    Nested Attributes
    • ingestion.serversString[]

      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.

  • oauthReadyBoolean

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