# Streams

## Add a stream

<mark style="color:green;">`POST`</mark> `https://api-v2.acrcloud.com/api/bm-cs-projects/:pid/streams`

#### Path Parameters

| Name                                  | Type   | Description |
| ------------------------------------- | ------ | ----------- |
| pid<mark style="color:red;">\*</mark> | string | Project Id. |

#### Headers

| Name          | Type   | Description      |
| ------------- | ------ | ---------------- |
| Authorization | string | Bearer token     |
| Accept        | string | application/json |
| Content-Type  | string | application/json |

#### Request Body

| Name                                           | Type    | Description                                                                                          |
| ---------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------- |
| stream\_urls<mark style="color:red;">\*</mark> | array   |                                                                                                      |
| name<mark style="color:red;">\*</mark>         | string  |                                                                                                      |
| config\_id<mark style="color:red;">\*</mark>   | integer | Please see the config list [here](https://console.acrcloud.com/bm/?region=eu-west-1#/custom-configs) |
| user\_defined                                  | string  | User-defined stream metadata                                                                         |

{% tabs %}
{% tab title="201 Cake successfully retrieved." %}

```
{
    "data":
        {
            "stream_id":"s-AO****",
            "uid":19,
            "mcp_id":12417,
            "stream_type":"Audio",
            "name":"asdfasdf",
            "state":"Running",
            "code":0,
            "stream_urls":[
                "http://*******"
            ],
            "current_url":"http://*******",
            "region":"eu-west-1",
            "user_defined":null,
            "pitch_shift":0,
            "check_pitch_shift":0,
            "remark":"",
            "created_at":"2020-06-07 07:42:16",
            "updated_at":"2021-01-04 10:06:37",
            "record_video":0,
            "stream_rec_type":0,
            "epg":"",
            "config":{
                "id":1,
                "name":"non-realtime for music",
                "uid":0,
                "rec_length":10,
                "interval":0,
                "rec_timeout":5,
                "monitor_timeout":25,
                "noise":1,
                "delay":1,
                "record":{
                    "record":0,
                    "record_after":8,
                    "record_before":5
                },
                "created_at":"2018-05-31T03:20:53.000000Z"
            },
            "timemap":0,
            "ucf":0
        }
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Curl" %}

```bash
curl --location --request POST 'https://api-v2.acrcloud.com/api/bm-cs-projects/{your_project_id}/streams' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {your token}' \
--header 'Content-Type: application/json' \
--data-raw '{"stream_urls":["https://streamurl.com/1234"],"name":"test","config_id":3, "user_defined":{"country":"France"}}'
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api-v2.acrcloud.com/api/bm-cs-projects/{your_project_id}/streams"

payload = {
  "stream_urls": [
    "https://streamurl.com/1234"
  ],
  "name": "test",
  "config_id": 3,
  "user_defined": {"country": "France"}
}
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {your token}',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, json=payload)

print(response.text)

```

{% endtab %}
{% endtabs %}

## List streams in a project

<mark style="color:blue;">`GET`</mark> `https://api-v2.acrcloud.com/api/bm-cs-projects/:pid/streams`

#### Path Parameters

| Name | Type   | Description    |
| ---- | ------ | -------------- |
| pid  | string | The Project ID |

#### Query Parameters

| Name          | Type   | Description                                                           |
| ------------- | ------ | --------------------------------------------------------------------- |
| timemap       | number | 0 or 1                                                                |
| state         | string | All,Running,Timeout,Paused,Invalid URL,Mute,Other. Default is All.    |
| search\_value | string | Search by Name, StreamID, URL, User-defind, Remark                    |
| sort          | string | sort by 'created\_at', 'stream\_id', 'name', Default is 'created\_at' |
| order         | string | order by desc or asc, default is desc.                                |

#### Headers

| Name          | Type   | Description      |
| ------------- | ------ | ---------------- |
| Authorization | string | Bearer token     |
| Accept        | string | application/json |

{% tabs %}
{% tab title="200 " %}

```
{
  "data": [
    {
      "stream_id": "s-At*****",
      "uid": 19,
      "mcp_id": 12417,
      "stream_type": "Audio",
      "name": "test",
      "state": "Running",
      "code": 0,
      "stream_urls": [
        "http://*******"
      ],
      "current_url": "http://*******",
      "region": "eu-west-1",
      "user_defined": null,
      "pitch_shift": 0,
      "check_pitch_shift": 0,
      "remark": "",
      "created_at": "2019-09-19 09:59:17",
      "updated_at": "2021-02-21 23:03:04",
      "record_video": 0,
      "stream_rec_type": 0,
      "epg": "",
      "config": {
        "id": 15,
        "name": "non-realtime and recording stream",
        "uid": 72,
        "rec_length": 10,
        "interval": 0,
        "rec_timeout": 5,
        "monitor_timeout": 25,
        "noise": 1,
        "delay": 1,
        "record": {
          "record": 10,
          "record_after": 0,
          "record_before": 0
        },
        "created_at": "2018-07-26T03:19:15.000000Z"
      },
      "timemap": 1,
      "ucf": 0
    }
  ],
  "links": {
    "first": "https://api-v2.acrcloud.com/api/bm-cs-projects/12848/streams?page=1",
    "last": "https://api-v2.acrcloud.com/api/bm-cs-projects/12848/streams?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "https://api-v2.acrcloud.com/api/bm-cs-projects/12848/streams",
    "per_page": 50,
    "to": 1,
    "total": 1
  }
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Curl" %}

```bash
curl --location --request GET 'https://api-v2.acrcloud.com/api/bm-cs-projects/13528/streams' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {your token}'
```

{% endtab %}
{% endtabs %}

## Update a stream

<mark style="color:orange;">`PUT`</mark> `https://api-v2.acrcloud.com/api/bm-cs-projects/:pid/streams/:stream_id`

#### Path Parameters

| Name       | Type   | Description    |
| ---------- | ------ | -------------- |
| pid        | number | The project id |
| stream\_id | string | The stream id  |

#### Headers

| Name          | Type   | Description      |
| ------------- | ------ | ---------------- |
| Authorization | string | Bearer token     |
| Accept        | string | application/json |
| Content-type  | string | application/json |

#### Request Body

| Name          | Type   | Description                           |
| ------------- | ------ | ------------------------------------- |
| name          | string | The stream name                       |
| stream\_urls  | array  | The stream urls                       |
| config\_id    | number | The config id                         |
| user\_defined | object | User-defined metadata for this stream |

{% tabs %}
{% tab title="200 " %}

```
{
    "data":
        {
            "stream_id":"s-At*****",
            "uid":19,
            "mcp_id":12417,
            "stream_type":"Audio",
            "name":"test2",
            "state":"Running",
            "code":0,
            "stream_urls":[
                "https://*******"
            ],
            "current_url":"https://*******",
            "region":"eu-west-1",
            "user_defined":null,
            "pitch_shift":0,
            "check_pitch_shift":0,
            "remark":"",
            "created_at":"2020-06-07 07:42:16",
            "updated_at":"2021-01-04 10:06:37",
            "record_video":0,
            "stream_rec_type":0,
            "epg":"",
            "config":{
                "id":1,
                "name":"non-realtime for music",
                "uid":0,
                "rec_length":10,
                "interval":0,
                "rec_timeout":5,
                "monitor_timeout":25,
                "noise":1,
                "delay":1,
                "record":{
                    "record":0,
                    "record_after":8,
                    "record_before":5
                },
                "created_at":"2018-05-31T03:20:53.000000Z"
            },
            "timemap":0,
            "ucf":0
        }
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Curl" %}

```bash
curl --location --request PUT 'https://api-v2.acrcloud.com/api/bm-cs-projects/13528/streams/s-0xAHfNh' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {your token}' \
--header 'Content-Type: application/json' \
--data-raw '{"stream_urls":["https://streamurl.com/1234"],"name":"test2","config_id":1}'
```

{% endtab %}
{% endtabs %}

## Delete a stream

<mark style="color:red;">`DELETE`</mark> `https://api-v2.acrcloud.com/api/bm-cs-projects/:pid/streams/:stream_ids`

#### Path Parameters

| Name        | Type   | Description                           |
| ----------- | ------ | ------------------------------------- |
| pid         | number | The project id                        |
| stream\_ids | string | Multiple stream ids, separated by "," |

#### Headers

| Name          | Type   | Description      |
| ------------- | ------ | ---------------- |
| Authorization | string | Bearer token     |
| Accept        | string | application/json |

{% tabs %}
{% tab title="204 " %}

```
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Curl" %}

```bash
curl --location --request DELETE 'https://api-v2.acrcloud.com/api/bm-cs-projects/13528/streams/s-rHmM7rc' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {your token}'
```

{% endtab %}
{% endtabs %}

## Pause a stream

<mark style="color:orange;">`PUT`</mark> `https://api-v2.acrcloud.com/api/bm-cs-projects/:pid/streams/:stream_ids/pause`

#### Path Parameters

| Name        | Type   | Description                                  |
| ----------- | ------ | -------------------------------------------- |
| pid         | number |                                              |
| stream\_ids | string | One or multiple stream ids, separated by ',' |

#### Headers

| Name          | Type   | Description  |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## Restart a stream

<mark style="color:orange;">`PUT`</mark> `https://api-v2.acrcloud.com/api/bm-cs-projects/:pid/streams/:stream_ids/restart`

#### Path Parameters

| Name        | Type   | Description                                  |
| ----------- | ------ | -------------------------------------------- |
| pid         | string |                                              |
| stream\_ids | string | One or multiple stream ids, separated by ',' |

#### Headers

| Name          | Type   | Description  |
| ------------- | ------ | ------------ |
| Authorization | string | Bearer token |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}