# Live Streaming
Our *REST APIs* use standard *HTTP* response codes, authentication, and verbs, and return *JSON-encoded responses*. Using these APIs, you will be able to start a live event and stream the content to our network, which will deliver that content to your audiences. Once a live entity is created, Uiza allocates dedicated resources and return an *RTMP* server to ingest and deliver your stream. The overall framework is articulated in the diagram below.
## **Step 1: Create a live entity**
To start streaming, you need a [`live_entity`](https://docs.uiza.io/api-reference/live-entities) to be created with resources allocated, ready to broadcast the live signal. You could create a live entity by using ***Create A Live Entity*** ***API***.
## /v1/live\_entities
`POST` `https://api.uiza.sh/v1/live_entities`
#### Request Body
| Name | Type | Description |
| ----------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name | string | The name of your live entity. |
| region | string | Choose the region closest to the location of your streamer. |
| description | string | The description of your live entity (maximum is 1000 characters) |
| dvr | boolean | Indicates whether Digital Video Record (DVR) is enabled for the `live_entity`. Set as `true` to enable and as `false` to disable. The default value is false. |
| encode | boolean | Indicates whether encoding mode is enabled for the `live_entity`. Set as `true` to enable and as `false` to disable. The default value is false, when the encode is true, it required a `preset_id`. |
| preset\_id | string | The identifier of the `video_preset` to be applied when encoding your signal. |
| relay | array | A list of ingest servers to be relayed. Contains `url` and `key` and `name` (optional) in each ingest server. |
{% tabs %}
{% tab title="200 " %}
{% tabs %}
{% tab title=" live\_entities without encoding" %}
```
"id": "2b970a39-874a-4d2a-be8a-fd445646d74c",
"name": "Test event without encoding",
"description": "Event for Test",
"region": "in-bangalore-1",
"status": "init",
"dvr": false,
"encode": false,
"ingest": null,
"playback": null,
"relay": [
{
"url": "rtmp://youtu.be/live",
"key": "Abco1",
"name": "Youtube 1"
}
],
"preset": null,
"created_at": "2020-03-23T07:22:34Z",
"updated_at": "2020-03-23T07:22:34Z"
}
```
{% endtab %}
{% tab title=" live\_entities with encoding" %}
```
{
"id": "b7f02d48-d0ec-4c34-86d1-247a38eda4e1",
"name": "Test event with encoding",
"description": "Event for Test",
"ingest": null,
"playback": null,
"relay": [
{
"url": "rtmp://youtu.be/live",
"key": "Abco1",
"name": "Youtube 1"
}
],
"region": "in-bangalore-1",
"status": "init",
"dvr": false,
"encode": true,
"preset": {
"id": "9432fa62-5988-11ea-883b-028fc5698662",
"name": "Uiza LIVE 720p",
"description": "",
"is_default": true,
"profiles": [
{
"id": "85844e8b-6281-11ea-883b-028fc5698662",
"name": "720p H264 30fps Normal Latency",
"segment_duration": 4,
"orientation": "landscape",
"video_profile": {
"video_resolution": "720",
"video_codec": "H264",
"video_bitrate": "2000K",
"video_frame_rate": "30"
},
"audio_profile": {
"audio_channel": "2",
"audio_codec": "AAC",
"audio_bitrate": "128K",
"audio_frame_rate": "1"
}
}
],
"created_at": "2020-02-27T17:42:52Z",
"updated_at": "2020-02-29T16:47:34Z"
},
"created_at": "2020-03-23T07:22:34Z",
"updated_at": "2020-03-23T07:22:34Z"
}
```
{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}
{% code title="Sample Request" %}
```go
curl -X POST https://api.uiza.sh/v1/live_entities \
-H 'Authorization: uap-c1ffbff4db954ddcb050c6af0b43ba56-41193b64' \
-d '{"name": "Test Event", "region": "in-bangalore-1", "description": "Test 1"}'
```
{% endcode %}
{% hint style="info" %}
Please pay attention that you entered a supported region, else the API will return an error message. Defining correct region helps Uiza allocates the resource that is closest to the streamer location. This will minimize the risks of network issues and reduce the impact on your business. While we are adding more and more regions to Uiza Network, please check the current available regions below:
`in-bangalore-1` (Bangalore - India)
`in-mumbai-1` (Mumbai - India)
`sg-singapore-1`(Singapore)
{% endhint %}
## **Step 2: Retrieve a live entity**
You will need the `ingest.key` and `ingest.url` to configure your broadcasting software. These 2 attributes could be retrieved by using the `id` you get in the response in ***Step 1*** for the ***Retrieve an entity*** API.
{% hint style="warning" %}
It is important that the value of the **`status`** you get from the response is **`ready`**, meaning that resources have been allocated and ready to ingest and broadcast your live feed. If the **`status`** of your entity is **`init`**, meaning that Uiza is still allocating resources for your entity and your live signal will not be able to be ingested and broadcasted during this process. Please, be patient and keep requesting for the entity's information until you get the **`ready`** status. This process may take up to 1 minute.
{% endhint %}
## /v1/live\_entities/:id
`GET` `https://api.uiza.sh/v1/live_entities/:id`
#### Path Parameters
| Name | Type | Description |
| ---- | ------ | ------------------------------------------------------------------ |
| id | string | The unique identifier of a live entity to be retrieved information |
{% tabs %}
{% tab title="200 " %}
```
{
"id": "2b970a39-874a-4d2a-be8a-fd445646d74c",
"name": "Test Event",
"description": "Test 1",
"ingest": {
"url": "rtmp://f45dd07a0e-in.uizadev.io/transcode",
"key": "live_TB62vHgxSY"
},
"playback": {
"hls": "https://f45dd07a0e.uizadev.io/fmp4/22013d8a-d5fa-48f0-9a63-1f471ca9e81d/master.m3u8"
},
"region": "in-bangalore-1",
"status": "ready",
"dvr": false,
"broadcast": "offline",
"created_at": "2019-12-11T02:47:04Z",
"updated_at": "2019-12-16T02:53:30Z"
}
```
{% endtab %}
{% endtabs %}
{% code title="Sample Request" %}
```go
curl -X GET https://api.uiza.sh/v1/live_entities/2b970a39-874a-4d2a-be8a-fd445646d74c \
-H 'Authorization: uap-c1ffbff4db954ddcb050c6af0b43ba56-41193b64'
```
{% endcode %}
{% hint style="info" %}
You could also set up a [webhook](https://docs.uiza.io/api-reference/webhook_endpoints) to be notified automatically when your `live_entity` is ready.
{% endhint %}
## **Step 3: Configure your broadcasting software and start broadcasting**
Most available broadcasting software uses [RTMP protocol](https://en.wikipedia.org/wiki/Real-Time_Messaging_Protocol) which requires a *server's URL* and a *Stream Key* to direct the live signal to the ingest servers. Use the `ingest.url` and `ingest.key` obtained at **Step 2** to configure your broadcasting software in their Settings. The following are the 2 most popular broadcasting software that we strongly recommend.
{% hint style="info" %}
**OBS Studio** (Available for Mac, Windows, and Linux**)** - Get it [here](https://obsproject.com/).
{% endhint %}
{% hint style="info" %}
**Streamlabs (**The best live streaming app for iPhone & Android**)** - Get it [here](https://streamlabs.com/mobile-app).
{% endhint %}
Once you have configured the `ingest.url` and `ingest.key`, you could start streaming right away.
## **Step 4: Configure the playback link to your player and start watching your live stream!**
The playback links (`hls` for HLS streaming and `mpd` for MPEG-dash streaming) of your live entity is the value of `playback` returned in ***Step 2*****.** With the HLS link obtained, you could play your live stream by these methods:
1. Configure the HLS link to Player SDK.
2. Paste the HLS link to Safari and play directly with Apple's native player.
3. Install the HLS extension and play it on Google Chrome browser.
The `mpd` video format could be played natively by [Microsoft Edge](https://www.microsoftedgeinsider.com/en-us/).
By following these *4 steps*, you will be able to live stream your event using Uiza:pray:. We understand that this beta version of ours requires quite some amount of manual involvement, but we are working hard to deliver a more delightful experience with more APIs and automation. If you are ready to live-stream your first event, let's move on to the ***API Reference***.