Ocyss/srs-auth / .agents/skills/internal-docs-for-srs
internal-docs-for-srs
FlaggedRoute SRS and Oryx tasks to the smallest relevant set of trusted project documentation and maintain the project documentation bundled with this skill. Use whenever support or development work requires locating, choosing, reading, creating, updating, or reviewing SRS documentation, or whenever Oryx work requires project documentation for deployment, streaming, authentication, recording to local or S3-compatible storage, restreaming, virtual live, camera, transcoding, HTTPS, APIs, callbacks, AI features, or development. Includes the C++ media server documentation, Oryx project documentation, website pages, changelog, executable API examples, and next-generation Go server and performance documentation.
references/cpp-docs/doc/http-api.md
View on GitHub---
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;
}
# Authentication for the HTTP API. Basic and Bearer authentication protect APIs under /api/.
# Bearer authentication can optionally protect WebRTC signaling APIs under /rtc/.
auth {
# whether enable the HTTP AUTH.
# Overwrite by env SRS_HTTP_API_AUTH_ENABLED
# default: off
enabled on;
# The authentication type. Supported values are basic and bearer.
# Required when authentication is enabled.
# Overwrite by env SRS_HTTP_API_AUTH_TYPE
type basic;
# The token of Bearer authentication. Required when type is bearer.
# Overwrite by env SRS_HTTP_API_AUTH_TOKEN
token secret-token;
# Whether Bearer authentication also protects WebRTC signaling APIs under /rtc/,
# including WHIP and WHEP. Requires enabled on and type bearer.
# Overwrite by env SRS_HTTP_API_AUTH_RTC_BEARER_ENABLED
# default: off
rtc_bearer_enabled off;
# 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`.
### Basic Authentication
```bash
# conf/http.api.auth.basic.conf
http_api {
enabled on;
listen 1985;
auth {
enabled on;
type basic;
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_TYPE=basic \
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
### Bearer Token Authentication
Bearer authentication protects the SRS HTTP API with a token sent in the
`Authorization` request header. By default, WebRTC signaling APIs remain
unprotected by Bearer authentication. Set the type to `bearer` and configure a
non-empty token:
```bash
# conf/http.api.auth.bearer.conf
http_api {
enabled on;
listen 1985;
auth {
enabled on;
type bearer;
token srs-api-token;
rtc_bearer_enabled off;
}
}
```
The equivalent environment variables are:
```bash
env SRS_HTTP_API_AUTH_ENABLED=on \
SRS_HTTP_API_AUTH_TYPE=bearer \
SRS_HTTP_API_AUTH_TOKEN=srs-api-token \
./objs/srs -c conf/srs.conf
```
Include the token in each API request:
```bash
curl -H 'Authorization: Bearer srs-api-token' \
http://127.0.0.1:1985/api/v1/versions
```
To protect WHIP, WHEP, and other WebRTC signaling requests under `/rtc/`, also
enable RTC Bearer authentication:
```bash
SRS_HTTP_API_AUTH_RTC_BEARER_ENABLED=on
```
Or set `rtc_bearer_enabled on;` in `http_api.auth`. The WHIP and WHEP clients
must then send the same header:
```bash
curl -H 'Authorization: Bearer srs-api-token' \
-H 'Content-Type: application/sdp' --data-binary @offer.sdp \
'http://127.0.0.1:1985/rtc/v1/whip/?app=live&stream=livestream'
```
Requests with a missing or incorrect token receive HTTP `401 Unauthorized` and
the response header `WWW-Authenticate: Bearer`.
`SRS_HTTP_API_AUTH_TOKEN` protects the SRS server's own HTTP API and, when
`SRS_HTTP_API_AUTH_RTC_BEARER_ENABLED=on`, its WebRTC signaling APIs. It is
separate from proxy registration authentication and heartbeat credentials.
> Note: Basic and Bearer authentication protect APIs under `/api/`. Basic does
> not apply to WebRTC signaling APIs. Bearer protects `/rtc/` only when
> `rtc_bearer_enabled` is on. Neither type protects files served by the HTTP
> server.
Bearer authentication can be combined with [HTTP callbacks](./http-callback.md).
When RTC Bearer authentication is enabled, a WHIP or WHEP request must first
pass Bearer authentication, and SRS then invokes `on_publish` or `on_play` for
stream-specific authorization. When RTC Bearer authentication is disabled, the
HTTP callback can authorize WHIP and WHEP by itself.
Winlin 2015.8

Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |