1. Home
  2. Knowledge Base
  3. Caster.fm Cloud
  4. API Documentation
  5. API Requests
Searching...

API Requests

Table of Contents

Account & Server Information

To get the account and server information make GET request to the following URL:
https://hub.cloud.caster.fm/private/accountInfo?token={PRIVATE_TOKEN}
If the request is successful an HTTP status code 200 will be returned along with the following JSON:

JSON
{
  "name": "Some User",
  "email": "[email protected]",
  "public_token": "97824ed0-ee56-4d2c-ba29-efbcb76794c5",
  "streaming_server_port": 10002,
  "streaming_server_ready": 0,
  "channels_count": 2,
  "streaming_server": {
    "id": "2d1f4206-95a3-4dd7-9b27-651df07ccbf6",
    "name": "Sapir",
    "area": "US-Washington",
    "domain": "sapircast.caster.fm",
    "ip_address": "173.244.216.28"
  },
  "channels": [
    {
      "id": "27b44a7c-b2f5-4934-91a5-887f93073b70",
      "name": "Rock Radio",
      "timezone": "Asia/Jerusalem",
      "country": "AX",
      "language": "ace",
      "genre": "kids_and_family",
      "streaming_server_mountpoint": "Li2Yn",
      "streaming_server_password": "DhkhAQ2TKh"
    }
  ],
  "subscription": {
    "plan_id": "premium-xl",
    "addons_count": 1,
    "listeners_slots": 500,
    "max_channels": 4,
    "bitrate": 128,
    "podcasts_recorder": {
      "duration": 3,
      "amount": 15,
      "protected": false
    },
    "protected_stream": false,
    "plan_name": "Premium - XL",
    "addons": [
      {
        "addon_id": "additional-broadcast-channel-XL",
        "quantity": 3,
        "addon_name": "Additional Broadcast Channels"
      }
    ]
  }
}

ACCOUNT

  • public_token – the public token will be used to render widgets
  • streaming_server_port – the port of your Icecast 2 server

STREAMING_SERVER
YOUR STREAMING SERVER DETAILS.

  • domain – the server hostname/domain name
  • ip_address – the server ip address

CHANNELS
AN ARRAY OF YOUR CHANNELS.

  • id – the internal channel id, required for getting the recordings for the channel
  • streaming_server_mountpoint – the Icecast 2 mount-point name
  • streaming_server_password – the Icecast 2 broadcast password

SUBSCRIPTION
YOUR ACCOUNT SUBSCRIPTION INFORMATION AND LIMITS

  • listeners_slots – maximum listeners slots for each channel
  • bitrate – maximum broadcast bitrate for each channel
  • protected_stream – if FALSE, it means that the direct stream link is available and don’t require an auth code to listen.
  • podcasts_recorder[duration] – maximum duration in hours of recorded podcasts
  • podcasts_recorder[amount] – maximum number of recorded podcasts for each channel

Fields That Are Required For Broadcasting
Since each channel is an Icecast 2 Mount-Point, you need to broadcast to each channel separately.
Below is a mapping of the fields required to setup your broadcast software.
Server Host/IP => streaming_server[domain]
Port => streaming_server_port
Username => “source”
Mount-Point => / + channels[X][streaming_server_mountpoint]
(eg. if the value of the streaming_server_mountpoint field is Li2Yn, the mount-point you will need to set at your broadcast software is /Li2Yn )
Password => channels[X][streaming_server_password]

JSON
{
  "name": "Some User",
  "email": "[email protected]",
  "public_token": "97824ed0-ee56-4d2c-ba29-efbcb76794c5",
  "streaming_server_port": 10002,
  "streaming_server_ready": 0,
  "channels_count": 2,
  "streaming_server": {
    "id": "2d1f4206-95a3-4dd7-9b27-651df07ccbf6",
    "name": "Sapir",
    "area": "US-Washington",
    "domain": "sapircast.caster.fm",
    "ip_address": "173.244.216.28"
  },
  "channels": [
    {
      "id": "27b44a7c-b2f5-4934-91a5-887f93073b70",
      "name": "Rock Radio",
      "timezone": "Asia/Jerusalem",
      "country": "AX",
      "language": "ace",
      "genre": "kids_and_family",
      "streaming_server_mountpoint": "Li2Yn",
      "streaming_server_password": "DhkhAQ2TKh"
    }
  ],
  "subscription": {
    "plan_id": "premium-xl",
    "addons_count": 1,
    "listeners_slots": 500,
    "max_channels": 4,
    "bitrate": 128,
    "podcasts_recorder": {
      "duration": 3,
      "amount": 15,
      "protected": false
    },
    "protected_stream": false,
    "plan_name": "Premium - XL",
    "addons": [
      {
        "addon_id": "additional-broadcast-channel-XL",
        "quantity": 3,
        "addon_name": "Additional Broadcast Channels"
      }
    ]
  }
}

Starting & Stopping the Server

Starting the server

To start the server make a POST request to the following URL:
https://hub.cloud.caster.fm/private/server/start?token={PRIVATE_TOKEN}
If the request is successful an HTTP status code 200 will be returned along with the following JSON:

JSON
{
  "success": true,
  "error": null
}

If trying to start the server while its already online, an HTTP status code 406 will be returned with the following JSON:

JSON
{
  "success": false,
  "error": {
    "message": "Server already running",
    "uuid": ""
  }
}

Stopping the server

To start the server make a POST request to the following URL:
https://hub.cloud.caster.fm/private/server/stop?token={PRIVATE_TOKEN}
If the request is successful an HTTP status code 200 will be returned along with the following JSON:

JSON
{
  "success": true,
  "error": null
}

If trying to stop the server while its not online, an HTTP status code 406 will be returned with the following JSON:

JSON
{
  "success": true,
  "error": null
}

Changing Broadcast Password

Channel Specific Resource
Since the broadcast password is channel specific (eg. each channel has its own broadcast password) you will need to specify the channel id (as returned at the Account & Server Information request.)

To generate a new broadcast password for a channel make a POST request to the following URL:
https://hub.cloud.caster.fm/channel/{CHANNEL_ID}/change_password?token={PRIVATE_TOKEN}
If the request is successful an HTTP status code 200 will be returned along with the following JSON:

JSON
{
  "success": true,
  "error": null
}

The newly generated broadcast password will be returned within the next Account & Server Information request you’ll make.

Recordings Management

List recordings

Channel Specific Resource
Since the broadcast password is channel specific (eg. each channel has its own recordings) you will need to specify the channel id (as returned at the Account & Server Information request.)

To get a list of the recordings for a channel make a GET request to the following URL:
https://hub.cloud.caster.fm/podcasts/{CHANNEL_ID}?token={PRIVATE_TOKEN}
If the request is successful an HTTP status code 200 will be returned along with the following JSON:

JSON
[
  {
    "id": "1e4f5a41-f563-44db-abfb-728138761446",
    "name": "Unnamed Broadcast",
    "recorded_at": "2020-06-11T17:32:48+03:00",
    "url": "//sapircast.caster.fm/podcast/1/27b44a7c-b2f5-4934-91a5-887f93073b70/1591885968.mp3"
  },
  {
    "id": "5c990517-7e4d-49ab-b028-9bcb08134542",
    "name": "Unnamed Broadcast",
    "recorded_at": "2020-05-23T18:57:24+03:00",
    "url": "//sapircast.caster.fm/podcast/1/27b44a7c-b2f5-4934-91a5-887f93073b70/1590249444.mp3"
  }
  ...
]

Update recording title

To update a recording name/title make a POST request to the following URL:
https://hub.cloud.caster.fm/podcasts/{CHANNEL_ID}/{PODCAST_ID}/update?token={PRIVATE_TOKEN}
with the desired recording name as a request parameter: ‘name’
The ‘name’ parameter must be present at the request and have maximum of 250 characters.
If the request is successful an HTTP status code 200 will be returned along with the following JSON:

JSON
{
  "success": true,
  "error": null
}

Remove a recording

To delete a recording make a POST request to the following URL:
https://hub.cloud.caster.fm/podcasts/{CHANNEL_ID}/{PODCAST_ID}/delete?token={PRIVATE_TOKEN}
If the request is successful an HTTP status code 200 will be returned along with the following JSON:

JSON
{
  "success": true,
  "error": null
}

Error Handling

Whenever something goes wrong with a request to the API or when the request was invalid an HTTP error response code will be returned.

In most cases an error response will have an HTTP error code and the following JSON syntax:

JSON
{
    "success": false,
    "error": {
        "message": "A description of the error",
        "uuid": "dfe70935-f0b4-406e-b523-03d6c95a3521" // Can be also null
    }
}


Some requests have their specific error codes which are described at the request documentation while there are some global error codes that can be returned by all requests:

401 – INVALID OR NO TOKEN HAS BEEN SPECIFIED

Returned for both Private and Public API’s when the token provided is invalid or when not present at the request at all.

403 – ACCOUNT HAS BEEN SUSPENDED

Returned if the account was suspended. the date and reason for the suspension will be provided at the ‘message’ property of the JSON response.

404 – RESOURCE WASN’T FOUND

Returned when a resource looked for was not found or the supplied id was invalid.

405 – METHOD NOT ALLOWED

Returned whenever trying to make a GET request to a POST endpoint or vice versa.

429 – TOO MANY REQUESTS

Returned when too many requests has been made to a throttled endpoint.

503 – SYSTEM IS DOWN FOR MAINTENANCE

Returned if the API system is down for a maintenance

Updated on August 17, 2023
Was this article helpful?
Yes No

Related Articles