---
title: HTTP API
sidebar_label: HTTP API
hide_title: false
hide_table_of_contents: false
---

# HTTP API

SRS provides HTTP api, to external application to manage SRS, and support crossdomain for js.

Once HTTP API enabled, you can use [srs-console](http://ossrs.net/console/) to connect to your SRS server.

The workflow is:

```text
+-------------------------+               +-------+
+ Chrome/Your Application +--HTTP-API-->--+  SRS  +
+-------------------------+               +-------+
```

You can use Chrome or your application, to request the HTTP API of SRS to get the state of SRS.

## Goals

The HTTP API of SRS follows the simple priciple:

* Only provides API in json format, both request and response are json.
* Please use [srs-console](https://github.com/ossrs/srs-console) to access API.
* When error, response in HTTP status or code in json.

## Build

SRS always enable the http api, read [configure](./install.md)

```bash
./configure && make
```

## Config

The config also need to enable it:

```bash
listen              1935;
# system statistics section.
# the main cycle will retrieve the system stat,
# for example, the cpu/mem/network/disk-io data,
# the http api, for instance, /api/v1/summaries will show these data.
# @remark the heartbeat depends on the network,
#       for example, the eth0 maybe the device which index is 0.
stats {
    # the index of device ip.
    # we may retrieve more than one network device.
    # default: 0
    network         0;
    # the device name to stat the disk iops.
    # ignore the device of /proc/diskstats if not configed.
    disk            sda sdb xvda xvdb;
}
# api of srs.
# the http api config, export for external program to manage srs.
# user can access http api of srs in browser directly, for instance, to access by:
#       curl http://192.168.1.170:1985/api/v1/reload
# which will reload srs, like cmd killall -1 srs, but the js can also invoke the http api,
# where the cli can only be used in shell/terminate.
http_api {
    # whether http api is enabled.
    # default: off
    enabled         on;
    # the http api listen entry is <[ip:]port>
    # for example, 192.168.1.100:1985
    # where the ip is optional, default to 0.0.0.0, that is 1985 equals to 0.0.0.0:1985
    # default: 1985
    listen          1985;
    # whether enable crossdomain request.
    # default: on
    crossdomain     on;
    # the HTTP RAW API is more powerful api to change srs state and reload.
    raw_api {
        # whether enable the HTTP RAW API.
        # Overwrite by env SRS_HTTP_API_RAW_API_ENABLED
        # default: off
        enabled off;
        # whether enable rpc reload.
        # Overwrite by env SRS_HTTP_API_RAW_API_ALLOW_RELOAD
        # default: off
        allow_reload off;
        # whether enable rpc query.
        # Always off by https://github.com/ossrs/srs/issues/2653
        #allow_query off;
        # whether enable rpc update.
        # Always off by https://github.com/ossrs/srs/issues/2653
        #allow_update off;
    }
    # the auth is authentication for http api
    auth {
        # whether enable the HTTP AUTH.
        # Overwrite by env SRS_HTTP_API_AUTH_ENABLED
        # default: off
        enabled         on;
        # The username of Basic authentication:
        # Overwrite by env SRS_HTTP_API_AUTH_USERNAME
        username        admin;
        # The password of Basic authentication:
        # Overwrite by env SRS_HTTP_API_AUTH_PASSWORD
        password        admin;
    }
    # For https_api or HTTPS API.
    https {
        # Whether enable HTTPS API.
        # default: off
        enabled on;
        # The listen endpoint for HTTPS API.
        # default: 1986
        listen 1986;
        # The SSL private key file, generated by:
        #       openssl genrsa -out server.key 2048
        # default: ./conf/server.key
        key ./conf/server.key;
        # The SSL public cert file, generated by:
        #       openssl req -new -x509 -key server.key -out server.crt -days 3650 -subj "/C=CA/ST=Toronto/L=Toronto/O=Me/OU=Me/CN=ossrs.io"
        # default: ./conf/server.crt
        cert ./conf/server.crt;
    }
}
vhost __defaultVhost__ {
}
```

The `http_api` enable the HTTP API, and `stats` used for SRS to stat the system info, including:

* network: Used for heartbeat to report the network info, where heartbeat used to report system info.
* disk: Used to stat the specified disk iops. You can use command `cat /proc/diskstats` to get the right disk names, for instance, xvda.

## Start

Start SRS: `./objs/srs -c http-api.conf`

Access api, open the url in web browser: 

* [http://127.0.0.1:1985/api/v1](http://127.0.0.1:1985/api/v1)
* [https://127.0.0.1:1986/api/v1](https://127.0.0.1:1986/api/v1)

> Remark: Please use your server ip instead.

## Performance

The HTTP api supports 370 request per seconds, please test by AB(Apache Benchmark).

## Access Api

Use web brower, or curl, or other http library.

SRS provides api urls list, no need to remember:
* code, an int error code. 0 is success.
* urls, the url lists, can be access.
* data, the last level api serve data.

Root directory:

```bash
# curl http://192.168.1.102:1985/
    "urls": {
        "api": "the api root"
    }
```

Go on:

```bash
# curl http://192.168.1.102:1985/api/v1/versions
        "major": 0,
        "minor": 9,
        "revision": 43,
        "version": "0.9.43"
```

Or:

```bash
# curl http://192.168.1.102:1985/api/v1/authors
        "primary_authors": "xxx",
        "contributors_link": "https://github.com/ossrs/srs/blob/master/AUTHORS.txt",
        "contributors": "xxx"
```

The Api of SRS is self-describes api.

## Error Code

SRS response error in both HTTP status or HTTP body.

For example, SRS response HTTP error, where HTTP status not 200:

```
winlin:~ winlin$ curl -v http://127.0.0.1:1985 && echo ""
< HTTP/1.1 404 Not Found
< Connection: Keep-Alive
< Content-Length: 9
< Content-Type: text/plain; charset=utf-8
< Server: SRS/2.0.184
< 
Not Found
```

For example, SRS response code not 0 when HTTTP Status 200:

```
winlin:~ winlin$ curl -v http://127.0.0.1:1985/api/v1/tests/errors && echo ""
< HTTP/1.1 200 OK
< Connection: Keep-Alive
< Content-Length: 12
< Content-Type: application/json
< Server: SRS/2.0.184
< 
{"code":100}
```

User should handle these two error style.

## Crossdomain

SRS HTTP API supports js crossdomain, so the html/js can invoke http api of srs。

SRS support two main CROS styles:

* OPTIONS: JQuery can directly access the CROS, where the brower will send an OPTIONS first, then the API request.
* JSONP: JQuery/Angularjs can send JSONP CROS request to SRS API, where specifes the function name by QueryString `callback`.
* JSONP-DELETE: JSONP only support GET, so we use the `method` in QueryString to override the HTTP method for JSONP.

For example, the JSONP crossdomain request:

```
GET http://localhost:1985/api/v1/vhosts/?callback=JSON_CALLBACK
JSON_CALLBACK({"code":0,"server":13449})
GET http://localhost:1985/api/v1/vhosts/100?callback=JSON_CALLBACK&method=DELETE
JSON_CALLBACK({"code":0})
```

## HTTPS API

SRS supports HTTPS API by turn the `https` on:

```
http_api {
    enabled         on;
    listen          1985;
    https {
        # Whether enable HTTPS API.
        # default: off
        enabled on;
        # The listen endpoint for HTTPS API.
        # default: 1990
        listen 1990;
        # The SSL private key file, generated by:
        #       openssl genrsa -out server.key 2048
        # default: ./conf/server.key
        key ./conf/server.key;
        # The SSL public cert file, generated by:
        #       openssl req -new -x509 -key server.key -out server.crt -days 3650 -subj "/C=CA/ST=Toronto/L=Toronto/O=Me/OU=Me/CN=ossrs.io"
        # default: ./conf/server.crt
        cert ./conf/server.crt;
    }
}
```

> Remark: Please use your HTTPS key and cert file.

> Note: To enable the HTTPS live streaming, please read [HTTPS FLV Live Stream](./flv.md#https-flv-live-stream)

## HTTP and HTTPS Proxy

SRS works well with HTTP/HTTPS proxies such as [Nginx](./http-server.md#nginx-proxy), [HTTPX](./http-server.md#httpx-proxy),
[CaddyServer](./http-server.md#caddy-proxy), and so on.

## Server ID

Each response of api contains a `server` field, which identify the server. When ServerID changed, SRS already restarted, all information before is invalid.

## API Navigation

SRS provides the Navigation of APIs.

User can access the `http://192.168.1.102:1985/api/v1`, where:

| API | Example  | Description |
| --- | -------- | ---------   |
| server | 4481  | The identity of SRS   |
| versions | /api/v1/versions  | the version of SRS |
| summaries | /api/v1/summaries | the summary(pid, argv, pwd, cpu, mem) of SRS |
| rusages  | /api/v1/rusages | the rusage of SRS |
| self_proc_stats | /api/v1/self_proc_stats | the self process stats |
| system_proc_stats | /api/v1/system_proc_stats | the system process stats |
| meminfos | /api/v1/meminfos | the meminfo of system |
| authors | /api/v1/authors | the license, copyright, authors and contributors |
| features | /api/v1/features | the supported features of SRS |
| requests | /api/v1/requests | the request itself, for http debug |
| vhosts | /api/v1/vhosts | manage all vhosts or specified vhost |
| streams | /api/v1/streams | manage all streams or specified stream |
| clients | /api/v1/clients | manage all clients or specified client, default query top 10 clients |
| configs | /api/v1/configs | RAW API for CUID the configs |
| publish | /rtc/v1/publish/ | The push stream API for WebRTC |
| play | /rtc/v1/play/ | The play stream API for WebRTC |

## WebRTC Publish

In order to push stream over WebRTC to SRS, SRS supports [WHIP](https://datatracker.ietf.org/doc/draft-ietf-wish-whip/).
The request is defined as:

```text
POST /rtc/v1/whip/?app=live&stream=livestream

Body in SDP, the Content-type is application/sdp:

v=0
......
a=ssrc:2064016335 label:c8243ce9-ace5-4d17-9184-41a2543101b5
```

SRS responses the SDP answer as the HTTP response:

```text
v=0
......
a=candidate:1 1 udp 2130706431 172.18.0.4 8000 typ host generation 0
```

> Note: The HTTP Status is 201, not 200, according to WHIP specification.

Please also see examples at [srs.sdk.js](https://github.com/ossrs/srs/blob/develop/trunk/research/players/js/srs.sdk.js) and [srs-unity: Publisher](https://github.com/ossrs/srs-unity#usage-publisher).

## WebRTC Play

In order to pull stream over WebRTC from SRS, SRS also supports [WHEP](https://datatracker.ietf.org/doc/draft-murillo-whep/). 
The request is defined as:

```text
POST /rtc/v1/whep/?app=live&stream=livestream

Body in SDP, the Content-type is application/sdp:

v=0
......
a=ssrc:2064016335 label:c8243ce9-ace5-4d17-9184-41a2543101b5
```

> Note: Although WHIP is defined to push stream to SRS, but you're able to use it for pulling stream from SRS. There is another [WHEP](https://datatracker.ietf.org/doc/draft-murillo-whep/) for players, but not a RFC draft.

SRS responses the SDP answer as the HTTP response:

```
v=0
......
a=candidate:1 1 udp 2130706431 172.18.0.4 8000 typ host generation 0
```

> Note: The HTTP Status is 201, not 200, according to WHIP specification.

Please also see examples at [srs.sdk.js](https://github.com/ossrs/srs/blob/develop/trunk/research/players/js/srs.sdk.js) and [srs-unity: Player](https://github.com/ossrs/srs-unity#usage-player).

## Summaries

User can get the system summaries, for instance, the memory, cpu, network, load usage.

Please access the url `http://192.168.1.170:1985/api/v1/summaries`

## Vhosts

SRS provides http api to query all vhosts.

The http api vhost url: `http://192.168.1.102:1985/api/v1/vhosts`

To process specified vhost by id, for instance `http://192.168.1.102:1985/api/v1/vhosts/3756`

## Streams

SRS provides http api to query all streams.

The http api stream url: `http://192.168.1.102:1985/api/v1/streams`

Parameters in query string:

* `?start=N`: The start index, default is 0.
* `?count=N`: The max number of result, default is 10.

To process specified stream by id, for instance `http://192.168.1.102:1985/api/v1/streams/3756`

## Clients

SRS provides http api to query clients.

The http api client url: `http://192.168.1.102:1985/api/v1/clients`

Parameters in query string:

* `?start=N`: The start index, default is 0.
* `?count=N`: The max number of result, default is 10.

To process specified client by id, for instance `http://192.168.1.102:1985/api/v1/clients/3756`

## Kickoff Client

SRS provides HTTP RESTful api to kickoff user:

```
DELETE /api/v1/clients/{id}
```

User can get the id of client to kickoff:

```
GET /api/v1/clients
```

User can get the id of publish client from streams api:

```
GET /api/v1/streams
or GET /api/v1/streams/6745
```

The client cid is the info from stream api `stream.publish.cid`:

```
1. GET http://192.168.1.170:1985/api/v1/streams/6745
2. Response stream.publish.cid:
stream: {
    publish: {
        active: true,
        cid: 107
    }
}
3. DELETE http://192.168.1.170:1985/api/v1/clients/107
```

Remark: User can use [HTTP REST Tool](http://ossrs.net/srs.release/http-rest/index.html) to send a request.

Remark: User can use linux tool `curl` to start HTTP request. For example:

```
curl -v -X GET http://192.168.1.170:1985/api/v1/clients/426 && echo ""
curl -v -X DELETE http://192.168.1.170:1985/api/v1/clients/426 && echo ""
```

## Persistence Config

This feature is disabled by SRS 4.0.

## HTTP RAW API

SRS supports powerful HTTP RAW API, while other server only support `Read API`, for instance, to get the stat of server. SRS supports `Write API`, which can `Reload` or change server state.

<b>Remark:</b> User must enable the HTTP RAW API, in config section `http_api` to enable the `http_api.raw_api.enabled`, or SRS will response error code 1061.

```
http_api {
    enabled         on;
    listen          1985;
    raw_api {
        enabled             on;
        allow_reload        on;
    }
}
```

The supported HTTP RAW APi of SRS is:

* `Raw`: To query the HTTP RAW API config.
* `Reload`: To reload the SRS.

### Raw

| Key | DESC | 
| ---- | ---- |
| feature | Query the HTTP RAW API info. |
| url  | `/api/v1/raw?rpc=raw` |
| curl | `curl http://127.0.0.1:1985/api/v1/raw?rpc=raw` |
| config | No config |
| params | No params|

### RAW Reload

| Key | DESC | 
| ---- | ---- |
| feature | Reload is the same to `killall -1 srs` to reload the config |
| url  | `/api/v1/raw?rpc=reload` |
| curl | `curl http://127.0.0.1:1985/api/v1/raw?rpc=reload` |
| params | No params |

### Other RAW APIs

Other RAW APIs are disabled by SRS 4.0.

## Authentication

Starting from version `5.0.152+` or `6.0.40+`, SRS supports HTTP API authentication, which can be enabled by configuring `http_api.auth`.

```bash
# conf/http.api.auth.conf
http_api {
    enabled on;
    listen 1985;
    auth {
        enabled on;
        username admin;
        password admin;
    }
}
```

Otherwise, you can use environment variables to enable it:

```bash
env SRS_HTTP_API_ENABLED=on SRS_HTTP_SERVER_ENABLED=on \
    SRS_HTTP_API_AUTH_ENABLED=on SRS_HTTP_API_AUTH_USERNAME=admin SRS_HTTP_API_AUTH_PASSWORD=admin \
    ./objs/srs -e
```

Then, you can access the following urls to verify it:
- Prompt for username and password: http://localhost:1985/api/v1/versions
- URL with authentication: http://admin:admin@localhost:1985/api/v1/versions

To clean up the username and password, you can access the HTTP API with the username only:
- http://admin@localhost:1985/api/v1/versions

> Note: authentication is only enabled for the HTTP APIs, neither for the HTTP server nor the WebRTC HTTP APIs.

Winlin 2015.8

![](https://ossrs.io/gif/v1/sls.gif?site=ossrs.io&path=/lts/doc/en/v7/http-api)


