1 of 12

VirtualHost

Get Virtual Host List

Request

GET /v1/vhosts

Header

Authorization: Basic {credentials}

# Authorization
    Credentials for HTTP Basic Authentication created with <AccessToken>

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body

{
	"statusCode": 200,
	"message": "OK",
	"response": [
		"default",
		"service",
		"poc"
	]
}

# statusCode
	Same as HTTP Status Code
# message
	A human-readable description of the response code
# response
	Json array containing a list of virtual host names

401 Unauthorized

Authentication required

Header

WWW-Authenticate: Basic realm=”OvenMediaEngine”

Body

{
    "message": "[HTTP] Authorization header is required to call API (401)",
    "statusCode": 401
}

Create Virtual Host

Request

POST /v1/vhosts

Header

Authorization: Basic {credentials}

# Authorization
    Credentials for HTTP Basic Authentication created with <AccessToken>

Body

Configure virtual hosts to be created in Json array format.

[
    {
        "name": "vhost",
        "host": {
            "names": [
                "ome-dev.airensoft.com",
                "prod.airensoft.com"
            ],
            "tls": {
                "certPath": "/etc/pki/airensoft.com/_airensoft_com.crt",
                "chainCertPath": "/etc/pki/airensoft.com/_airensoft_com.ca-bundle",
                "keyPath": "/etc/pki/airensoft.com/_airensoft_com.key"
            }
        },

        "signedPolicy": {
            "enables": {
                "providers": "rtmp,webrtc,srt",
                "publishers": "webrtc,llhls"
            },
            "policyQueryKeyName": "policy",
            "secretKey": "aKq#1kj",
            "signatureQueryKeyName": "signature"
        },

        "admissionWebhooks": {
            "controlServerUrl": "https://control.server/admission",
            "enables": {
                "providers": "rtmp,webrtc,srt",
                "publishers": "webrtc,llhls"
            },
            "secretKey": "",
            "timeout": 3000
        },
        
        "origins": {
            "origin": [
                {
                    "location": "/app/rtsp",
                    "pass": {
                        "scheme": "rtsp",
                        "urls": {
                            "url": [
                                "rtsp.server:8554/ca-01"
                            ]
                        }
                    }
                }
            ]
        },

        "originMapStore": {
            "originHostName": "ome-dev.airensoft.com",
            "redisServer": {
                "auth": "!@#ovenmediaengine",
                "host": "redis.server:6379"
            }
        }
    },
    {
        "name": "vhost2",
        "host": {
            "names": [
                "ovenmediaengine.com"
            ],
            "tls": {
                "certPath": "/etc/pki/ovenmediaengine.com/_ovenmediaengine_com.crt",
                "chainCertPath": "/etc/pki/ovenmediaengine.com/_ovenmediaengine_com.ca-bundle",
                "keyPath": "/etc/pki/ovenmediaengine.com/_ovenmediaengine_com.key"
            }
        }
    }
]

# name (required)
    The virtual host name. Cannot be duplicated.

# host (required)
    ## names (required)
        The addresses(IP or Domain)of the host. 
    ## tls (optional)
        The certificate file path. Required if using TLS. 
        
# signedPolicy (optional)
    The SignedPolicy setting. Please refer to the manual for details.
    
# admissionWebhooks (optional)
    The AdmissionWebhooks setting. Please refer to the manual for details.
    
# origins (optional)
    The Origins setting. Please refer to the manual for details.

# originMapStore (optional)
    The OriginMapStore setting. Please refer to the manual for details.

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body

It responds with Json array for each request.

[
    {
        "message": "OK",
        "statusCode": 200,
        "response": {
            "name": "enterprise",

            "host": {
                "names": [
                    "ome-dev.airensoft.com",
                    "prod.airensoft.com"
                ],
                "tls": {
                    "certPath": "/etc/pki/airensoft.com/_airensoft_com.crt",
                    "chainCertPath": "/etc/pki/airensoft.com/_airensoft_com.ca-bundle",
                    "keyPath": "/etc/pki/airensoft.com/_airensoft_com.key"
                }
            },
            "signedPolicy": {
                "enables": {
                    "providers": "rtmp,webrtc,srt",
                    "publishers": "webrtc,llhls"
                },
                "policyQueryKeyName": "policy",
                "secretKey": "aKq#1kj",
                "signatureQueryKeyName": "signature"
            },
            "admissionWebhooks": {
                "controlServerUrl": "https://control.server/admission",
                "enables": {
                    "providers": "rtmp,webrtc,srt",
                    "publishers": "webrtc,llhls"
                },
                "secretKey": "",
                "timeout": 3000
            },
            "origins": {
                "origin": [
                    {
                        "location": "/app/rtsp",
                        "pass": {
                            "scheme": "rtsp",
                            "urls": {
                                "url": [
                                    "rtsp.server:8554/ca-01"
                                ]
                            }
                        }
                    }
                ]
            },
            "originMapStore": {
                "originHostName": "ome-dev.airensoft.com",
                "redisServer": {
                    "auth": "!@#ovenmediaengine",
                    "host": "redis.server:6379"
                }
            }
        }
    },
    {
        "message": "OK",
        "statusCode": 200,
        "response": {
            "name": "free",
            "host": {
                "names": [
                    "ovenmediaengine.com"
                ],
                "tls": {
                    "certPath": "/etc/pki/ovenmediaengine.com/_ovenmediaengine_com.crt",
                    "chainCertPath": "/etc/pki/ovenmediaengine.com/_ovenmediaengine_com.ca-bundle",
                    "keyPath": "/etc/pki/ovenmediaengine.com/_ovenmediaengine_com.key"
                }
            }
        }
    }
]

# statusCode
	Same as HTTP Status Code
# message
	A human-readable description of the response code
# response
	Created virtual host information

207 Multi-Status

There might be a mixture of responses.

Header

Content-Type: application/json

Body

It responds with Json array for each request.

[
    {
        "statusCode": 200,
        "message": "OK",
        "response": {
            "name": "enterprise",
            "host": {
                "names": [
            ...
    },
    {
        "statusCode": 409,
        "message": "Conflict",
        "response": {
            ...
        }
    }
}

# statusCode
    Same as HTTP Status Code
# message
    A human-readable description of the response code
# response
    Virtual host information created when statusCode is 200

400 Bad Request

Invalid request. Body is not a Json array or does not have a required value

401 Unauthorized

Authentication required

Header

WWW-Authenticate: Basic realm=”OvenMediaEngine”

Body

{
    "message": "[HTTP] Authorization header is required to call API (401)",
    "statusCode": 401
}

409 Conflict

A virtual host with that name already exists

Get Virtual Host Information

Request

GET /v1/vhosts/{vhost}

Header

Authorization: Basic {credentials}

# Authorization
    Credentials for HTTP Basic Authentication created with <AccessToken>

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body


    "message": "OK",
    "statusCode": 200
    "response": {
        "name": "default",
        "distribution": "ovenServer",

    "host": {
        "name": "default",
        "distribution": "ovenServer",

        "host": {
            "names": [
                "ome-dev.airensoft.com",
                "*"
            ],
            "tls": {
                "certPath": "/etc/pki/airensoft.com/_airensoft_com.crt",
                "chainCertPath": "/etc/pki/airensoft.com/_airensoft_com.ca-bundle",
                "keyPath": "/etc/pki/airensoft.com/_airensoft_com.key"
            }
        },
        
        "signedPolicy": {
            "enables": {
                "providers": "rtmp,webrtc,srt",
                "publishers": "webrtc,llhls"
            },
            "policyQueryKeyName": "policy",
            "secretKey": "aKq#1kj",
            "signatureQueryKeyName": "signature"
        },
        
        "admissionWebhooks": {
            "controlServerUrl": "https://control.server/admission",
            "enables": {
                "providers": "rtmp,webrtc,srt",
                "publishers": "webrtc,llhls"
            },
            "secretKey": "",
            "timeout": 3000
        },
        
        "origins": {
            "origin": [
                {
                    "location": "/app/rtsp",
                    "pass": {
                        "scheme": "rtsp",
                        "urls": {
                            "url": [
                                "rtsp.server:8554/ca-01"
                            ]
                        }
                    }
                }
            ]
        },

        "originMapStore": {
            "originHostName": "ome-dev.airensoft.com",
            "redisServer": {
                "auth": "!@#ovenmediaengine",
                "host": "redis.server:6379"
            }
        }
    }

# statusCode
	Same as HTTP Status Code
# message
	A human-readable description of the response code
# response
	Virtual host information

401 Unauthorized

Authentication required

Header

WWW-Authenticate: Basic realm=”OvenMediaEngine”

Body

{
    "message": "[HTTP] Authorization header is required to call API (401)",
    "statusCode": 401
}

404 Not Found

The given vhost name could not be found.

Body

{
    "message": "[HTTP] Could not find the virtual host: [default1] (404)",
    "statusCode": 404
}

Delete Virtual Host

Request

DELETE /v1/vhosts/{vhost}

Header

Authorization: Basic {credentials}

# Authorization
    Credentials for HTTP Basic Authentication created with <AccessToken>

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body

{
    "message": "OK",
    "statusCode": 200
}

# statusCode
	Same as HTTP Status Code
# message
	A human-readable description of the response code

401 Unauthorized

Authentication required

Header

WWW-Authenticate: Basic realm=”OvenMediaEngine”

Body

{
    "message": "[HTTP] Authorization header is required to call API (401)",
    "statusCode": 401
}

404 Not Found

The given vhost name could not be found.

Body

{
    "message": "[HTTP] Could not find the virtual host: [default1] (404)",
    "statusCode": 404
}

500 Internal Server Error

The request failed due to an error on the server. Check the server log for the reason of the error.

Body

{
    "message": "[HTTP] Internal Server Error (500)",
    "statusCode": 500
}

Reload Certificate

Reload All Certificates

Batch reload certificates of all Virtual Hosts. In case of failure, the existing certificate will continue to be used.

Request

POST /v1/vhosts:reloadAllCertificates

Header

Authorization: Basic {credentials}

# Authorization
    Credentials for HTTP Basic Authentication created with <AccessToken>

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body

{
    "message": "OK",
    "statusCode": 200
}

# statusCode
	Same as HTTP Status Code
# message
	A human-readable description of the response code

500 Internal Server Error

Failed to reload certificate. Keep the existing certificate. The reason for the failure can be found in the server logs.

Reload Certificate

Reload the certificate of the specified Virtual Hosts. In case of failure, the existing certificate will continue to be used.

Request

POST /v1/vhosts/{vhost}:reloadCertificate

Header

Authorization: Basic {credentials}

# Authorization
    Credentials for HTTP Basic Authentication created with <AccessToken>

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body

{
    "message": "OK",
    "statusCode": 200
}

# statusCode
    Same as HTTP Status Code
# message
    A human-readable description of the response code

500 Internal Server Error

Failed to reload certificate. Keep the existing certificate. The reason for the failure can be found in the server logs.

Application

Get Application List

List all application names in the virtual host.

Request

GET /v1/vhosts/{vhost}/apps

Header

Authorization: Basic {credentials}

# Authorization
    Credentials for HTTP Basic Authentication created with <AccessToken>

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body

{
	"statusCode": 200,
	"message": "OK",
	"response": [
		"app",
		"app2",
		"app3"
	]
}

# statusCode
	Same as HTTP Status Code
# message
	A human-readable description of the response code
# response
	Json array containing a list of application names

401 Unauthorized

Authentication required

Header

WWW-Authenticate: Basic realm=”OvenMediaEngine”

Body

{
    "message": "[HTTP] Authorization header is required to call API (401)",
    "statusCode": 401
}

404 Not Found

The given vhost name could not be found.

Body

{
    "message": "[HTTP] Could not find the virtual host: [default1] (404)",
    "statusCode": 404
}

Create Application

Create application in the virtual host

Request

POST /v1/vhosts/{vhost}/apps

Header

Authorization: Basic {credentials}

# Authorization
    Credentials for HTTP Basic Authentication created with <AccessToken>

Body

Configure applications to be created in Json array format.

[
    {
        "name": "app",
        "type": "live",
        "outputProfiles": {
            "outputProfile": [
                {
                    "name": "default",
                    "outputStreamName": "${OriginStreamName}",
                    "encodes": {
                        "audios": [
                            {
                                "name": "opus",
                                "codec": "opus",
                                "samplerate": 48000,
                                "bitrate": 128000,
                                "channel": 2,
                                "bypassIfMatch": {
                                    "codec": "eq"
                                }
                            },
                            {
                                "name": "aac",
                                "codec": "aac",
                                "samplerate": 48000,
                                "bitrate": 128000,
                                "channel": 2,
                                "bypassIfMatch": {
                                    "codec": "eq"
                                }
                            }
                        ],
                        "videos": [
                            {
                                "name": "bypass_video",
                                "bypass": true
                            }
                        ]
                    }
                }
            ]
        },
        "providers": {
            "ovt": {},
            "rtmp": {},
            "rtspPull": {},
            "srt": {},
            "webrtc": {}
        },
        "publishers": {
            "llhls": {},
            "ovt": {},
            "webrtc": {}
        }
    }
]
    
# name (required)
    Application name to create
    
# type (required)
    live - currently only support live
    
# outputProfiles (optional)
   Set OutputProfile for Transcoding. See the ABR and Transcoding chapter for             more details. If no outputProfiles are present in the request, a default outputProfile as above is configured.
   
# providers (optional)
    Configure providers. See the Live Source chapter for details. If providers are not present in the request, they are configured with default providers as above.

# publishers (optional)
    Configure publishers. See the Streaming chapter for details. If publishers are not present in the request, they are configured with default publishers as above.

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body

It responds with Json array for each request.

[
    {
        "statusCode": 200,
        "message": "OK",
        "response": {
            "name": "app",
            "outputProfiles": {
            ...

            "providers": {
                "ovt": {},
                "rtmp": {},
            ...
    },
    {
        "statusCode": 200,
        "message": "OK",
        "response": {
            ...
        }
    }
}

# statusCode
    Same as HTTP Status Code
# message
    A human-readable description of the response code
# response
    Created application information

207 Multi-Status

There might be a mixture of responses.

Header

Content-Type: application/json

Body

It responds with Json array for each request.

[
    {
        "statusCode": 200,
        "message": "OK",
        "response": {
            "name": "app",
            "outputProfiles": {
            ...

            "providers": {
                "ovt": {},
                "rtmp": {},
            ...
    },
    {
        "statusCode": 409,
        "message": "Conflict",
        "response": {
            ...
        }
    }
}

# statusCode
    Same as HTTP Status Code
# message
    A human-readable description of the response code
# response
    Application information created when statusCode is 200

400 Bad Request

Invalid request. Body is not a Json array or does not have a required value

401 Unauthorized

Authentication required

Header

WWW-Authenticate: Basic realm=”OvenMediaEngine”

Body

{
    "message": "[HTTP] Authorization header is required to call API (401)",
    "statusCode": 401
}

404 Not Found

The given vhost name could not be found.

Body

{
    "message": "[HTTP] Could not find the virtual host: [default1] (404)",
    "statusCode": 404
}

409 Conflict

An application name already exists

Get Application Information

Request

GET /v1/vhosts/{vhost}/apps/{app}

Header

Authorization: Basic {credentials}

# Authorization
    Credentials for HTTP Basic Authentication created with <AccessToken>

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body

{
    "statusCode": 200,
    "message": "OK",
    "response": {
        "dynamic": false,
        "name": "app",
        "type": "live",
        "outputProfiles": {
            "outputProfile": [
                {
                    "encodes": {
                        "audios": [
                            {
                                "bitrate": 128000,
                                "bypassIfMatch": {
                                    "codec": "eq"
                                },
                                "channel": 2,
                                "codec": "opus",
                                "name": "opus",
                                "samplerate": 48000
                            },
                            {
                                "bitrate": 128000,
                                "bypassIfMatch": {
                                    "codec": "eq"
                                },
                                "channel": 2,
                                "codec": "aac",
                                "name": "aac",
                                "samplerate": 48000
                            }
                        ],
                        "videos": [
                            {
                                "bypass": true,
                                "name": "bypass_video"
                            }
                        ]
                    },
                    "name": "bypass",
                    "outputStreamName": "${OriginStreamName}"
                }
            ]
        },
        "providers": {
            "ovt": {},
            "rtmp": {},
            "rtspPull": {},
            "srt": {},
            "webrtc": {}
        },
        "publishers": {
            "llhls": {},
            "ovt": {},
            "webrtc": {}
        }
    }
}

# statusCode
    Same as HTTP Status Code
# message
    A human-readable description of the response code
# response
    Application information

401 Unauthorized

Authentication required

Header

WWW-Authenticate: Basic realm=”OvenMediaEngine”

Body

{
    "message": "[HTTP] Authorization header is required to call API (401)",
    "statusCode": 401
}

404 Not Found

The given vhost name or application name could not be found.

Body

{
    "message": "[HTTP] Could not find the application: [default/app2] (404)",
    "statusCode": 404
}

Patch Application Information

Modify application settings. If this request succeeds, the Application will be restarted.

Request

PATCH /v1/vhosts/{vhost}/apps/{app}

Header

Authorization: Basic {credentials}

# Authorization
    Credentials for HTTP Basic Authentication created with <AccessToken>

Body

Write the value you want to modify. However, name and outputProfiles cannot be modified.

{
    "providers": {
        "webrtc": {
            "timeout": 60000
        }
    }
}

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body

{
    "statusCode": 200,
    "message": "OK",
    "response": {
        "dynamic": false,
        "name": "app",
        "type": "live",
        "outputProfiles": {
            "outputProfile": [
                {
                    "encodes": {
                        "audios": [
                            {
                                "bitrate": 128000,
                                "bypassIfMatch": {
                                    "codec": "eq"
                                },
                                "channel": 2,
                                "codec": "opus",
                                "name": "opus",
                                "samplerate": 48000
                            },
                            {
                                "bitrate": 128000,
                                "bypassIfMatch": {
                                    "codec": "eq"
                                },
                                "channel": 2,
                                "codec": "aac",
                                "name": "aac",
                                "samplerate": 48000
                            }
                        ],
                        "videos": [
                            {
                                "bypass": true,
                                "name": "bypass_video"
                            }
                        ]
                    },
                    "name": "bypass",
                    "outputStreamName": "${OriginStreamName}"
                }
            ]
        },
        "providers": {
            "ovt": {},
            "rtmp": {},
            "rtspPull": {},
            "srt": {},
            "webrtc": {
                "timeout": 60000
            }
        },
        "publishers": {
            "llhls": {},
            "ovt": {},
            "webrtc": {}
        }
    }
}

# statusCode
    Same as HTTP Status Code
# message
    A human-readable description of the response code
# response
    Mofified application information

400 Bad Request

Invalid request.

{
    "message": "[HTTP] Cannot change [name] using this API (400)",
    "statusCode": 400
}

401 Unauthorized

Authentication required

Header

WWW-Authenticate: Basic realm=”OvenMediaEngine”

Body

{
    "message": "[HTTP] Authorization header is required to call API (401)",
    "statusCode": 401
}

404 Not Found

The given vhost name or application name could not be found.

Body

{
    "message": "[HTTP] Could not find the application: [default/app2] (404)",
    "statusCode": 404
}

Delete Application

Request

DELETE /v1/vhosts/{vhost}/apps/{app}

Header

Authorization: Basic {credentials}

# Authorization
    Credentials for HTTP Basic Authentication created with <AccessToken>

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body

{
    "message": "OK",
    "statusCode": 200
}

# statusCode
	Same as HTTP Status Code
# message
	A human-readable description of the response code

401 Unauthorized

Authentication required

Header

WWW-Authenticate: Basic realm=”OvenMediaEngine”

Body

{
    "message": "[HTTP] Authorization header is required to call API (401)",
    "statusCode": 401
}

404 Not Found

The given vhost name or application name could not be found.

Body

{
    "message": "[HTTP] Could not find the application: [default/app2] (404)",
    "statusCode": 404
}

500 Internal Server Error

The request failed due to an error on the server. Check the server log for the reason of the error.

Body

{
    "message": "[HTTP] Internal Server Error (500)",
    "statusCode": 500
}

Output Profile

Get Output Profile List

Request

GET /v1/vhosts/{vhost}/apps/{app}/outputProfiles

Header

Authorization: Basic {credentials}

# Authorization
    Credentials for HTTP Basic Authentication created with <AccessToken>

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body

{
	"statusCode": 200,
	"message": "OK",
	"response": [
		"default",
		"audio_only"
	]
}

# statusCode
	Same as HTTP Status Code
# message
	A human-readable description of the response code
# response
	Json array containing a list of output profile names

401 Unauthorized

Authentication required

Header

WWW-Authenticate: Basic realm=”OvenMediaEngine”

Body

{
    "message": "[HTTP] Authorization header is required to call API (401)",
    "statusCode": 401
}

404 Not Found

The given vhost or application name could not be found.

Body

{
    "message": "[HTTP] Could not find the application: [vhost/app1] (404)",
    "statusCode": 404
}

Create Output Profile

Add an Output Profile to the Application. If this request succeeds, the application will be restarted.

Request

POST /v1/vhosts/{vhost}/apps/{app}/outputProfiles

Header

Authorization: Basic {credentials}

# Authorization
    Credentials for HTTP Basic Authentication created with <AccessToken>

Body

Configure output profiles to be created in Json array format.

[
  {
    "name": "bypass_profile",
    "outputStreamName": "${OriginStreamName}_bypass",
    "encodes": {
      "videos": [
        {
          "bypass": true
        }
      ],
      "audios": [
        {
          "bypass": true
        }
      ]
    }
  }
]

# name (required)
  The name of the output profile. cannot be duplicated

# outputStreamName (required)
  The name of the output stream to be created through this profile.
  
# encodes (required)
  encode profile list. It must have videos or audios, and must have at least one item.

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body

It responds with Json array for each request.

[
    {
        "statusCode": 200,
        "message": "OK",
        "response": {
            "name": "bypass_profile",
            "outputStreamName": "${OriginStreamName}_bypass",
            "encodes": {
                "audios": [],
                "videos": [
                    {
                        "bypass": true
                    }
                ]
            }
    },
    {
        "statusCode": 200,
        "message": "OK",
        "response": {
            ...
        }
    }
}

# statusCode
    Same as HTTP Status Code
# message
    A human-readable description of the response code
# response
    Created output profile information

207 Multi-Status

There might be a mixture of responses.

Header

Content-Type: application/json

Body

It responds with Json array for each request.

[
    {
        "statusCode": 200,
        "message": "OK",
        "response": {
            "name": "app",
            "outputProfiles": {
            ...

            "providers": {
                "ovt": {},
                "rtmp": {},
            ...
    },
    {
        "statusCode": 409,
        "message": "Conflict",
        "response": {
            ...
        }
    }
}

# statusCode
    Same as HTTP Status Code
# message
    A human-readable description of the response code
# response
    Output profile information created when statusCode is 200

400 Bad Request

Invalid request. Body is not a Json array or does not have a required value

401 Unauthorized

Authentication required

Header

WWW-Authenticate: Basic realm=”OvenMediaEngine”

Body

{
    "message": "[HTTP] Authorization header is required to call API (401)",
    "statusCode": 401
}

404 Not Found

The given vhost or application name could not be found.

Body

{
    "message": "[HTTP] Could not find the application: [vhost/app1] (404)",
    "statusCode": 404
}

409 Conflict

A output profile name already exists

Get Output Profile Information

Request

GET /v1/vhosts/{vhost}/apps/{app}/outputProfiles/{profile}

Header

Authorization: Basic {credentials}

# Authorization
    Credentials for HTTP Basic Authentication created with <AccessToken>

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body

{
    "statusCode": 200,
    "message": "OK",
    "response": {
        "name": "bypass_profile2",
        "outputStreamName": "${OriginStreamName}_bypass"
        "encodes": {
            "audios": [],
            "videos": [
                {
                    "bypass": true
                }
            ]
        }
    }
}

# statusCode
	Same as HTTP Status Code
# message
	A human-readable description of the response code
# response
	Output Profile information

401 Unauthorized

Authentication required

Header

WWW-Authenticate: Basic realm=”OvenMediaEngine”

Body

{
    "message": "[HTTP] Authorization header is required to call API (401)",
    "statusCode": 401
}

404 Not Found

The given vhost or application name could not be found.

Body

{
    "message": "[HTTP] Could not find the application: [vhost/app1] (404)",
    "statusCode": 404
}

Delete Output Profile

Delete output profile settings. If this request succeeds, the Application will be restarted.

Request

DELETE /v1/vhosts/{vhost}/apps/{app}/outputProfiles/{profile}

Header

Authorization: Basic {credentials}

# Authorization
    Credentials for HTTP Basic Authentication created with <AccessToken>

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body

{
    "message": "OK",
    "statusCode": 200
}

# statusCode
	Same as HTTP Status Code
# message
	A human-readable description of the response code

401 Unauthorized

Authentication required

Header

WWW-Authenticate: Basic realm=”OvenMediaEngine”

Body

{
    "message": "[HTTP] Authorization header is required to call API (401)",
    "statusCode": 401
}

404 Not Found

The given vhost or application name could not be found.

Body

{
    "message": "[HTTP] Could not find the application: [vhost/app1] (404)",
    "statusCode": 404
}

Record

Start Recording

Start recording the stream. If the requested stream does not exist on the server, this recording task is reserved. And when the stream is created, it automatically starts recording.

Request

POST /v1/vhosts/{vhost}/apps/{app}:startRecord

Header

Authorization: Basic {credentials}

# Authorization
    Credentials for HTTP Basic Authentication created with <AccessToken>

Body : Output the recorded video to a single file

{
    "id": "{unique_record_id}",
    "stream": {
        "name": "{output_stream_name}",
        "variantNames": []
    }
}

# id (required)
    unique ID to identify the recording task
    
# stream (required)
    ## name (required)
        output stream name
        
    ## variantNames (optional)
        Array of track names to record. If empty, all tracks will be 
        recorded. This value is Encodes.[Video|Audio|Data].Name in the
        OutputProfile setting.

Body : Output the recorded video to a file at intervals

{
  "id": "{unique_record_id}",
  "stream": {
    "name": "{output_stream_name}"
  },
  "interval": 60000,
  "segmentationRule": "discontinuity"
}

# id (required)
    unique ID to identify the recording task
    
# stream (required)
    ## name (required)
        output stream name
        
    ## variantNames (optional)
        Array of track names to record. If empty, all tracks will be 
        recorded. This value is Encodes.[Video|Audio|Data].Name in the
        OutputProfile setting.

# interval (optional)
    Recording time per file (milliseconds). Not allowed to use with schedule
    
# segmentationRule (optional)
    Define the policy for continuously or discontinuously timestamp 
    in divided recorded files.
    
    continuity : timestamp of recorded files is continuous
    discontinuity(default) : timestamp starts anew for each recorded file

Body : Output the recorded video to a file at the scheduled time

{
  "id": "{unique_record_id}",
  "stream": {
    "name": "{output_stream_name}"
  },
  "schedule" : "0 */1 *"
  "segmentationRule": "continuity"
}

# id (required)
    unique ID to identify the recording task
    
# stream (required)
    ## name (required)
        output stream name
        
    ## variantNames (optional)
        Array of track names to record. If empty, all tracks will be 
        recorded. This value is Encodes.[Video|Audio|Data].Name in the
        OutputProfile setting.

# schedule (optional)
    <Second Minute Hour> format, same as crontab syntax
    "10 */1 *" means to output the recorded file every 10 minutes of the hour
    Not allowed to use with schedule
    
# segmentationRule (optional)
    Define the policy for continuously or discontinuously timestamp 
    in divided recorded files.
    
    continuity : timestamp of recorded files is continuous
    discontinuity(default) : timestamp starts anew for each recorded file

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body

Please note that responses are incorrectly returned in Json array format for version 0.15.3 and earlier.

{
    "statusCode": 200,
    "message": "OK",
    "response": {
        "id": "2",
        "state": "ready",
        "vhost": "default",
        "app": "app",
        "stream": {
            "name": "stream",
            "trackIds": [],
            "variantNames": []
        },
        "interval": 60000,
        "segmentationRule": "discontinuity",
        "createdTime": "2023-03-15T21:15:20.113+09:00",
    }
}

# statusCode
	Same as HTTP Status Code
# message
	A human-readable description of the response code
# response
	Created recording task information

400 Bad Request

Invalid request.

401 Unauthorized

Authentication required

Header

WWW-Authenticate: Basic realm=”OvenMediaEngine”

Body

{
    "message": "[HTTP] Authorization header is required to call API (401)",
    "statusCode": 401
}

404 Not Found

The given vhost or application name could not be found.

Body

{
    "message": "[HTTP] Could not find the application: [vhost/app1] (404)",
    "statusCode": 404
}

409 Conflict

duplicate ID

Stop Recording

Request

POST /v1/vhosts/{vhost}/apps/{app}:stopRecord

Header

Authorization: Basic {credentials}

# Authorization
    Credentials for HTTP Basic Authentication created with <AccessToken>

Body

{
    "id": "{unique_record_id}"
}

# id (required)
    unique ID to identify the recording task

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body

{
    "statusCode": 200,
    "message": "OK",
}

# statusCode
	Same as HTTP Status Code
# message
	A human-readable description of the response code

400 Bad Request

Invalid request.

401 Unauthorized

Authentication required

Header

WWW-Authenticate: Basic realm=”OvenMediaEngine”

Body

{
    "message": "[HTTP] Authorization header is required to call API (401)",
    "statusCode": 401
}

404 Not Found

The given vhost/application name or id of recording task could not be found.

Body

{
    "message": "[HTTP] Could not find the application: [vhost/app1] (404)",
    "statusCode": 404
}

Get Recording State

Request

POST /v1/vhosts/{vhost}/apps/{app}:records

Header

Authorization: Basic {credentials}

# Authorization
    Credentials for HTTP Basic Authentication created with <AccessToken>

Body

{
    "id": "{unique_record_id}"
}

# id (optional)
    unique ID to identify the recording task. If no id is given in the request, the full list is returned.

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body

The response is Json array format.

{
    "statusCode": 200,
    "message": "OK",
    "response": [
        {
            "id": "2",
            "state": "recording",
            "vhost": "default",
            "app": "app",
            "stream": {
                "name": "stream",
                "trackIds": [],
                "variantNames": []
            },
            "interval": 60000,
            "segmentationRule": "discontinuity",
            "createdTime": "2023-03-15T21:15:20.113+09:00",
        },
        {
            "id": "3",
            ...
        }
    ]
}

# statusCode
	Same as HTTP Status Code
# message
	A human-readable description of the response code
# response
	Information of recording tasks. If there is no recording task, 
	response with empty array ("response": [])

401 Unauthorized

Authentication required

Header

WWW-Authenticate: Basic realm=”OvenMediaEngine”

Body

{
    "message": "[HTTP] Authorization header is required to call API (401)",
    "statusCode": 401
}

404 Not Found

The given vhost or application name could not be found.

Body

{
    "message": "[HTTP] Could not find the application: [vhost/app1] (404)",
    "statusCode": 404
}

State of Recording

The Recording task has the state shown in the table below. You can get the state in the Start Recording and Get Recording State API response.

Ready

Preparing to start or waiting for the stream to be created.

Started

In Progress

Stopping

Is stopping

Stopped

Error

Push

Start Push Publishing

Start push publishing the stream with SRT, RTMP or MPEG2-TS. If the requested stream does not exist on the server, this task is reserved. And when the stream is created, it automatically starts push publishing.

Request

POST /v1/vhosts/{vhost}/apps/{app}:startPush

Header

Authorization: Basic {credentials}

# Authorization
    Credentials for HTTP Basic Authentication created with <AccessToken>

Body : SRT

{
  "id": "{unique_push_id}",
  "stream": {
    "name": "{output_stream_name}",
    "variantNames": []
  },
  "protocol": "srt",
  "url": "srt://{host}[:port]?mode=caller&latency=120000&timeout=500000",
  "streamKey": ""
}

# id (required)
    unique ID to identify the task
    
# stream (required)
    ## name (required)
        output stream name
        
    ## variantNames (optional)
        Array of track names to publsh. 
        This value is Encodes.[Video|Audio|Data].Name in the OutputProfile
        setting.
        
        If empty, all tracks will be sent.

# protocol (required)
    srt
    
# url (required) 
    address of destination.
    options can be set in query-string format.
    
# streamKey (optional)
    not used with mpegts

In SRT Push Publisher, only the caller connection mode is supported.

Body : RTMP

{
  "id": "{unique_push_id}",
  "stream": {
    "name": "{output_stream_name}",
    "variantNames": [ "h264_fhd", "aac" ]
  },
  "protocol": "rtmp",
  "url":"rtmp://{host}[:port]/{app_name}",
  "streamKey":"{stream_name}"
}

# id (required)
    unique ID to identify the task
    
# stream (required)
    ## name (required)
        output stream name
        
    ## variantNames (optional)
        Array of track names to publsh. 
        This value is Encodes.[Video|Audio|Data].Name in the OutputProfile
        setting.
        
        If empty, The first track among video tracks (by ID) and the first 
        track among audio tracks (by ID) are selected automatically.

# protocol (required)
    rtmp
    
# url (required) 
    address of destination
    
# streamKey (required)
    RTMP stream key

Body : MPEG2-TS

{
  "id": "{unique_push_id}",
  "stream": {
    "name": "{output_stream_name}",
    "variantNames": []
  },
  "protocol": "mpegts",
  "url": "udp://{host}[:port]",
  "streamKey": ""
}

# id (required)
    unique ID to identify the task
    
# stream (required)
    ## name (required)
        output stream name
        
    ## variantNames (optional)
        Array of track names to publsh. 
        This value is Encodes.[Video|Audio|Data].Name in the OutputProfile
        setting.
        
        If empty, all tracks will be sent.

# protocol (required)
    mpegts
    
# url (required) 
    address of destination
    
# streamKey (optional)
    not used with mpegts

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body

Please note that responses are incorrectly returned in Json array format for version 0.15.3 and earlier.

{
    "statusCode": 200,
    "message": "OK",
    "response": {
        "id": "{unique_push_id}",
        "state": "ready",
            
        "vhost": "default",
        "app": "app",
        "stream": {
            "name": "{output_stream_name}",
            "trackIds": [],
            "variantNames": []
        },
            
        "protocol": "rtmp",
        "url": "rtmp://{host}[:port]/{app_name}",
        "streamKey": "{stream_name}",
            
        "sentBytes": 0,
        "sentTime": 0,
        "sequence": 0,
        "totalsentBytes": 0,
        "totalsentTime": 0,
            
        "createdTime": "2023-03-15T23:02:34.371+09:00",
        "startTime": "1970-01-01T09:00:00.000+09:00",
        "finishTime": "1970-01-01T09:00:00.000+09:00"
    }
}

# statusCode
    Same as HTTP Status Code
# message
    A human-readable description of the response code
# response
    Created push publishing task information

400 Bad Request

Invalid request.

401 Unauthorized

Authentication required

Header

WWW-Authenticate: Basic realm=”OvenMediaEngine”

Body

{
    "message": "[HTTP] Authorization header is required to call API (401)",
    "statusCode": 401
}

404 Not Found

The given vhost or application name could not be found.

Body

{
    "message": "[HTTP] Could not find the application: [vhost/app1] (404)",
    "statusCode": 404
}

409 Conflict

duplicate ID

Stop Push Publishing

Request

POST /v1/vhosts/{vhost}/apps/{app}:stopPush

Header

Authorization: Basic {credentials}

# Authorization
    Credentials for HTTP Basic Authentication created with <AccessToken>

Body

{
    "id": "{unique_push_id}"
}

# id (required)
    unique ID to identify the push publishing task

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body

{
    "statusCode": 200,
    "message": "OK",
}

# statusCode
	Same as HTTP Status Code
# message
	A human-readable description of the response code

400 Bad Request

Invalid request.

401 Unauthorized

Authentication required

Header

WWW-Authenticate: Basic realm=”OvenMediaEngine”

Body

{
    "message": "[HTTP] Authorization header is required to call API (401)",
    "statusCode": 401
}

404 Not Found

The given vhost/application name or id of recording task could not be found.

Body

{
    "message": "[HTTP] Could not find the application: [vhost/app1] (404)",
    "statusCode": 404
}

Get Push Publishing State

Request

POST /v1/vhosts/{vhost}/apps/{app}:pushes

Header

Authorization: Basic {credentials}

# Authorization
    Credentials for HTTP Basic Authentication created with <AccessToken>

Body

{
    "id": "{unique_push_id}"
}

# id (optional)
    unique ID to identify the push publishing task. If no id is given in the request, the full list is returned.

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body

The response is Json array format.

{
    "statusCode": 200,
    "message": "OK",
    "response": [
        {
            "id": "{unique_push_id}",
            "state": "started",
            
            "vhost": "default",
            "app": "app",
            "stream": {
                "name": "{output_stream_name}",
                "trackIds": [],
                "variantNames": []
            },
            
            "protocol": "rtmp",
            "url": "rtmp://{host}[:port]/{app_name}",
            "streamKey": "{stream_name}",
            
            "sentBytes": 0,
            "sentTime": 0,
            "sequence": 0,
            "totalsentBytes": 0,
            "totalsentTime": 0,
            
            "createdTime": "2023-03-15T23:02:34.371+09:00",
            "startTime": "1970-01-01T09:00:00.000+09:00",
            "finishTime": "1970-01-01T09:00:00.000+09:00"
        },
        {
            "id": "4",
            ...
        }
    ]
}

# statusCode
	Same as HTTP Status Code
# message
	A human-readable description of the response code
# response
	Information of recording tasks. If there is no recording task, 
	response with empty array ("response": [])

401 Unauthorized

Authentication required

Header

WWW-Authenticate: Basic realm=”OvenMediaEngine”

Body

{
    "message": "[HTTP] Authorization header is required to call API (401)",
    "statusCode": 401
}

404 Not Found

The given vhost or application name could not be found.

Body

{
    "message": "[HTTP] Could not find the application: [vhost/app1] (404)",
    "statusCode": 404
}

State of Push Publishing

The Push Publishing task has the state shown in the table below. You can get the state in the Start Push Publishing and Get Push Publishing State API response.

Ready

Preparing to start or waiting for the stream to be created.

Started

In Progress

Stopping

Is stopping

Stopped

Error

Stream

Get Stream List

Get all stream names in the {vhost name}/{app name} application.

Request

GET /v1/vhosts/{vhost}/apps/{app}/streams

Header

Authorization: Basic {credentials}

# Authorization
    Credentials for HTTP Basic Authentication created with <AccessToken>

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body

{
	"statusCode": 200,
	"message": "OK",
	"response": [
		"stream",
		"stream2"
	]
}

# statusCode
	Same as HTTP Status Code
# message
	A human-readable description of the response code
# response
	Json array containing a list of stream names

401 Unauthorized

Authentication required

Header

WWW-Authenticate: Basic realm=”OvenMediaEngine”

Body

{
    "message": "[HTTP] Authorization header is required to call API (401)",
    "statusCode": 401
}

404 Not Found

The given vhost name or app name could not be found.

Header

Content-Type: application/json

Body

{
    "statusCode": 404,
    "message": "Could not find the application: [default/non-exists] (404)"
}

Create Stream (Pull)

Create a stream by pulling an external URL. External URL protocols currently support RTSP and OVT.

Request

POST /v1/vhosts/{vhost}/apps/{app}/streams

Header

Authorization: Basic {credentials}
Content-Type: application/json

# Authorization
    Credentials for HTTP Basic Authentication created with <AccessToken>

Body

{
	"name": "new_stream_name",
	"urls": [
		"rtsp://192.168.0.160:553/app/stream",
		"url to pull the stream from - support OVT/RTSP",
		"Only urls with the same scheme can be sent as a group."
  	],
  	"properties":{
		"persistent": false,
		"noInputFailoverTimeoutMs": 3000,
		"unusedStreamDeletionTimeoutMs": 60000,
		"ignoreRtcpSRTimestamp": false
  	}
}

# name (required)
	Stream name to create
# urls (required)
	A list of URLs to pull streams from, in Json array format. 
	All URLs must have the same scheme.
# properties (optional)
	## persistent
		Created as a persistent stream, not deleted until DELETE
	## noInputFailoverTimeoutMs
		If no data is input during this period, the stream is deleted, 
		but ignored if persistent is true
	## unusedStreamDeletionTimeoutMs
		If no data is output during this period (if there is no viewer), 
		the stream is deleted, but ignored if persistent is true
	## ignoreRtcpSRTimestamp
		No waits RTCP SR and start stream immediately

Responses

201 Created

A stream has been created.

Header

Content-Type: application/json

Body

{
    "message": "Created",
    "statusCode": 201
}

# statusCode
    Same as HTTP Status Code
# message
    A human-readable description of the response code

400 Bad Request

Invalid request. Body is not a Json Object or does not have a required value

401 Unauthorized

Authentication required

Header

WWW-Authenticate: Basic realm=”OvenMediaEngine”

Body

{
    "message": "[HTTP] Authorization header is required to call API (401)",
    "statusCode": 401
}

404 Not Found

The given vhost name or app name could not be found.

Body

{
    "statusCode": 404,
    "message": "Could not find the application: [default/non-exists] (404)"
}

409 Conflict

A stream with the same name already exists

502 Bad Gateway

Failed to pull provided URL

500 Internal Server Error

Unknown error

Get Stream Info

Get detailed information of stream.

Request

GET /v1/vhosts/{vhost}/apps/{app}/streams/{stream}

Header

Authorization: Basic {credentials}

# Authorization
    Credentials for HTTP Basic Authentication created with <AccessToken>

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body

{
	"statusCode": 200,
	"message": "OK",
	"response": {
		"input": {
			"createdTime": "2021-01-11T03:45:21.879+09:00",
			"sourceType": "Rtmp",
			"tracks": [
			{
				"id": 0,
				"type": "Video",
				"video": {
					"bitrate": "2500000",
					"bypass": false,
					"codec": "H264",
					"framerate": 30.0,
					"hasBframes": false,
					"keyFrameInterval": 30,
					"height": 720,
					"width": 1280
				}
			},
			{
				"id": 1,				
				"audio": {
					"bitrate": "128000",
					"bypass": false,
					"channel": 2,
					"codec": "AAC",
					"samplerate": 48000
				},
				"type": "Audio"
			}
			]
		},
		"name": "stream",
		"outputs": [
		{
			"name": "stream",
			"tracks": [
			{
				"id": 0,
				"type": "Video",
				"video": {
					"bypass": true
				}
			},
			{
				"id": 1,					
				"audio": {
					"bypass": true
				},
				"type": "Audio"
			},
			{
				"id": 2,					
				"audio": {
					"bitrate": "128000",
					"bypass": false,
					"channel": 2,
					"codec": "OPUS",
					"samplerate": 48000
				},
				"type": "Audio"
			}
			]
		}
	]
	}
}


# statusCode
	Same as HTTP Status Code
# message
	A human-readable description of the response code
# response
	Details of the stream

Note

keyFrameInterval is GOP size

401 Unauthorized

Authentication required

Header

WWW-Authenticate: Basic realm=”OvenMediaEngine”

Body

{
    "message": "[HTTP] Authorization header is required to call API (401)",
    "statusCode": 401
}

404 Not Found

The given vhost name or app name could not be found.

Header

Content-Type: application/json

Body

{
    "statusCode": 404,
    "message": "Could not find the application or stream (404)"
}

Delete Stream

Delete Stream. This terminates the ingress connection.

The sender can reconnect after the connection is terminated. To prevent reconnection, you must use AccessControl.

Request

DELETE /v1/vhosts/{vhost}/apps/{app}/streams/{stream}

Header

Authorization: Basic {credentials}

# Authorization
    Credentials for HTTP Basic Authentication created with <AccessToken>

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body

{
	"statusCode": 200,
	"message": "OK",
}


# statusCode
	Same as HTTP Status Code
# message
	A human-readable description of the response code

401 Unauthorized

Authentication required

Header

WWW-Authenticate: Basic realm=”OvenMediaEngine”

Body

{
    "message": "[HTTP] Authorization header is required to call API (401)",
    "statusCode": 401
}

404 Not Found

The given vhost name or app name could not be found.

Header

Content-Type: application/json

Body

{
    "message": "[HTTP] Could not find the stream: [default/#default#app/stream] (404)",
    "statusCode": 404
}

Send Event

It allows you to insert events into streams. Right now events only support the ID3v2 format and only the LLHLS publisher handles it. Events delivered to LLHLS Publisher are inserted as emsg boxes within the m4s container.

Request

POST v1/vhosts/{vhost}/apps/{app}/streams/{stream}:sendEvent

Header

Authorization: Basic {credentials}

# Authorization
    Credentials for HTTP Basic Authentication created with <AccessToken>

Body

{
  "eventFormat": "id3v2",
  "eventType": "video",
  "events":[
      {
        "frameType": "TXXX",
        "info": "AirenSoft",
        "data": "OvenMediaEngine"
      },
      {
        "frameType": "TIT2",
        "data": "OvenMediaEngine 123"
      }
  ]
}

# eventFormat
  Currently only id3v2 is supported.
# eventType (Optional, Default : event)
  Select one of event, video, and audio. event inserts an event into every track. 
  video inserts events only on tracks of video type. 
  audio inserts events only on tracks of audio type.
# events
  It accepts only Json array format and can contain multiple events.
 
  ## frameType
    Currently, only TXXX and T??? (Text Information Frames, e.g. TIT2) are supported.
 ## info
    This field is used only in TXXX and is entered in the Description field of TXXX.
 ## data
    If the frameType is TXXX, it is entered in the Value field, 
    and if the frameType is "T???", it is entered in the Information field.

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body

{
	"statusCode": 200,
	"message": "OK",
}

# statusCode
	Same as HTTP Status Code
# message
	A human-readable description of the response code
# response
	Json array containing a list of stream names

400 Bad Request

Invalid request. Body is not a Json Object or does not have a required value

401 Unauthorized

Authentication required

Header

WWW-Authenticate: Basic realm=”OvenMediaEngine”

Body

{
    "message": "[HTTP] Authorization header is required to call API (401)",
    "statusCode": 401
}

404 Not Found

The given vhost name or app name could not be found.

Body

{
    "statusCode": 404,
    "message": "Could not find the application: [default/non-exists] (404)"
}

HLS Dump

The LLHLS Dump feature can be controlled with this API.

Start Dump

Request

POST /v1/vhosts/{vhost name}/apps/{app}/streams/{stream}:startHlsDump

Header

Authorization: Basic {credentials}
Content-Type: application/json

# Authorization
    Credentials for HTTP Basic Authentication created with <AccessToken>

Body

{
  "outputStreamName": "stream",
  "id": "unique_dump_id",
  "outputPath": "/tmp/",
  "playlist" : ["llhls.m3u8", "abr.m3u8"],
  "infoFile": "/home/abc/xxx/unique_info_file_name.info",
  "userData": "access_key_id='AKIAXFOT7EWH3ZA4XXXX'"
}

# outputStreamName (required)
  The name of the output stream created with OutputProfile.
# id (required)
  ID for this API request.
# outputPath (required)
  Directory path to output. The directory must be writable by the OME process. 
  OME will create the directory if it doesn't exist.
# playlist (optional)
  Dump the master playlist set in outputPath. It must be entered 
  in Json array format, and multiple playlists can be specified.
# infoFile (optional)
  This is the name of the DB file in which the information of the dumped files is 
  updated. If this value is not provided, no file is created. An error occurs 
  if a file with the same name exists. (More details below)
# userData (optional)
  If infoFile is specified, this data is written to infoFile. Does not work 
  if infoFile is not specified.

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body

{
	"statusCode": 200,
	"message": "OK",
	"response": [
		"stream",
		"stream2"
	]
}

# statusCode
	Same as HTTP Status Code
# message
	A human-readable description of the response code
# response
	Json array containing a list of stream names

400 Bad Request

Invalid request. Body is not a Json Object or does not have a required value

401 Unauthorized

Authentication required

Header

WWW-Authenticate: Basic realm=”OvenMediaEngine”

Body

{
    "message": "[HTTP] Authorization header is required to call API (401)",
    "statusCode": 401
}

404 Not Found

The given vhost name or app name or stream name could not be found.

Header

Content-Type: application/json

Body

{
    "statusCode": 404,
    "message": "Could not find the application: [default/non-exists] (404)"
}

500 Internal Server Error

Unknown error

Stop Dump

Request

POST /v1/vhosts/<vhost name>/apps/{app}/streams/{stream}:stopHlsDump

Header

Authorization: Basic {credentials}
Content-Type: application/json

# Authorization
    Credentials for HTTP Basic Authentication created with <AccessToken>

Body

{
  "outputStreamName": "stream",
  "id": "dump_id"
}

# outputStreamName (required)
 The name of the output stream created with OutputProfile.
# id (optional)
  This is the id passed when calling the startHlsDump API. 
  If id is not passed, all dump in progress at outputStreamName is aborted.

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body

{
	"statusCode": 200,
	"message": "OK",
	"response": [
		"stream",
		"stream2"
	]
}

# statusCode
	Same as HTTP Status Code
# message
	A human-readable description of the response code
# response
	Json array containing a list of stream names

400 Bad Request

Invalid request. Body is not a Json Object or does not have a required value

401 Unauthorized

Authentication required

Header

WWW-Authenticate: Basic realm=”OvenMediaEngine”

Body

{
    "message": "[HTTP] Authorization header is required to call API (401)",
    "statusCode": 401
}

404 Not Found

The given vhost name or app name or stream name could not be found.

Header

Content-Type: application/json

Body

{
    "statusCode": 404,
    "message": "Could not find the application: [default/non-exists] (404)"
}

500 Internal Server Error

Unknown error

InfoFile

The info file is continuously updated after the dump file is written. It is in XML format and is as follows. will continue to be added.

<HLSDumpInfo>
  <UserData>~~~</UserData>
  <Stream>/default/app/stream</Stream>
  <Status>Running | Completed | Error </Status>
  <Items>
    <Item>
      <Seq>0</Seq>
      <Time>~~~</Time>
      <File>~~~</File>
    </Item>
    ...
    <Item>
      <Seq>1</Seq>
      <Time>~~~</Time>
      <File>/tmp/abc/xxx/298182/chunklist_0_video_llhls.m3u8</File>
    </Item>
    ...
    <Item>
      <Seq>2</Seq>
      <Time>~~~</Time>
      <File>chunklist_0_video_llhls.m3u8</File>
    </Item>
  </Items>
</HLSDumpInfo>

Conclude HLS Live

For live streaming of certain events, it may be necessary to immediately stop the HLS live stream and switch to VoD after the HLS live broadcast ends. This API transitions to VoD by stopping segment updates for LL-HLS and HLS streams and inserting #EXT-X-ENDLIST. By using this API with a Scheduled Channel, you can implement additional application services.

Request

POST v1/vhosts/{vhost}/apps/{app}/streams/{stream}:concludeHlsLive

Header

Authorization: Basic {credentials}

# Authorization
    Credentials for HTTP Basic Authentication created with <AccessToken>

Body

{}

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body

{
	"statusCode": 200,
	"message": "OK",
}

# statusCode
	Same as HTTP Status Code
# message
	A human-readable description of the response code

400 Bad Request

Invalid request. Body is not a Json Object or does not have a required value

401 Unauthorized

Authentication required

Header

WWW-Authenticate: Basic realm=”OvenMediaEngine”

Body

{
    "message": "[HTTP] Authorization header is required to call API (401)",
    "statusCode": 401
}

404 Not Found

The given vhost name or app name could not be found.

Body

{
    "statusCode": 404,
    "message": "Could not find the application: [default/non-exists] (404)"
}

ScheduledChannel

ScheduledChannel allows you to create a live channel by scheduling pre-recorded files has been added to OvenMediaEngine. Other services or software call this Pre-recorded Live or File Live, but OvenMediaEngine plans to expand the function to organize live channels as a source, so we named it Scheduled Channel.

ScheduledChannel can be controlled by API or file. For more information about ScheduledChannel, see below.

The body of the API all has the same structure as the ScheduledChannel schedule file.

Get Channel List

Get all scheduled channels in the {vhost name}/{app name} application.

Request

GET /v1/vhosts/{vhost}/apps/{app}/scheduledChannels

Header

Responses

200 Ok

The request has succeeded

Header

Body

401 Unauthorized

Authentication required

Header

Body

404 Not Found

The given vhost name or app name could not be found.

Header

Body

Create Channel

Create a Scheduled channel.

Request

POST /v1/vhosts/{vhost}/apps/{app}/scheduledChannels

Header

Body

Responses

201 Created

A stream has been created.

Header

Body

400 Bad Request

Invalid request. Body is not a Json Object or does not have a required value

401 Unauthorized

Authentication required

Header

Body

404 Not Found

The given vhost name or app name could not be found.

Body

409 Conflict

A stream with the same name already exists

502 Bad Gateway

Failed to pull provided URL

500 Internal Server Error

Unknown error

Patch Schedule

Update the schedule. <Stream> cannot be PATCHed.

Request

PATCH /v1/vhosts/{vhost}/apps/{app}/scheduledChannels/{channel name}

Header

Body

Write the value you want to modify. However, name and outputProfiles cannot be modified.

Responses

200 Ok

The request has succeeded

Header

Body

400 Bad Request

Invalid request.

401 Unauthorized

Authentication required

Header

Body

404 Not Found

The given vhost name or application name could not be found.

Body

Get Channel Info

Get detailed information of scheduled channel. It also provides information about the currently playing program and item.

Request

GET /v1/vhosts/{vhost}/apps/{app}/scheduledChannels/{channel name}

Header

Responses

200 Ok

The request has succeeded

Header

Body

401 Unauthorized

Authentication required

Header

Body

404 Not Found

The given vhost name or app name could not be found.

Header

Body

Delete Channel

Delete Scheduled Channel

Request

DELETE /v1/vhosts/{vhost}/apps/{app}/scheduledChannels/{channel name}

Header

Responses

200 Ok

The request has succeeded

Header

Body

401 Unauthorized

Authentication required

Header

Body

404 Not Found

The given vhost name or app name could not be found.

Header

Body

MultiplexChannel

Using MultiplexChannel, you can combine multiple internal streams into one ABR stream, or duplicate the stream and send it to another application.

MultiplexChannel can be controlled by API or file. See below for more information about MultiplexChannel.

The body of the API all has the same structure as the mux file.

Get Channel List

Get all multiplex channels in the {vhost name}/{app name} application.

Request

GET /v1/vhosts/{vhost}/apps/{app}/multiplexChannels

Header

Authorization: Basic {credentials}

# Authorization
    Credentials for HTTP Basic Authentication created with <AccessToken>

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body

{
    "message": "OK",
    "response": [
        "stream"
    ],
    "statusCode": 200
}

# statusCode
	Same as HTTP Status Code
# message
	A human-readable description of the response code
# response
	Json array containing a list of stream names

401 Unauthorized

Authentication required

Header

WWW-Authenticate: Basic realm=”OvenMediaEngine”

Body

{
    "message": "[HTTP] Authorization header is required to call API (401)",
    "statusCode": 401
}

404 Not Found

The given vhost name or app name could not be found.

Header

Content-Type: application/json

Body

{
    "statusCode": 404,
    "message": "Could not find the application: [default/non-exists] (404)"
}

Create Channel

Create a multiplex channel.

Request

POST /v1/vhosts/{vhost}/apps/{app}/multiplexChannels

Header

Authorization: Basic {credentials}
Content-Type: application/json

# Authorization
    Credentials for HTTP Basic Authentication created with <AccessToken>

Body

{
  "outputStream": {
    "name": "stream"
  },
  "sourceStreams": [
    {
      "name": "input1",
      "url": "stream://default/app/input1",
      "trackMap": [
        {
          "sourceTrackName": "bypass_video",
          "newTrackName": "input1_video",
          "bitrateConf": 5000000,
          "framerateConf": 30
        },
        {
          "sourceTrackName": "bypass_audio",
          "newTrackName": "input1_audio",
          "bitrateConf": 128000
        }
      ]
    },
    {
      "name": "input2",
      "url": "stream://default/app/input2",
      "trackMap": [
        {
          "sourceTrackName": "bypass_video",
          "newTrackName": "input2_video",
          "bitrateConf": 1000000,
          "framerateConf": 30
        },
        {
          "sourceTrackName": "bypass_audio",
          "newTrackName": "input2_audio",
          "bitrateConf": 128000
        }
      ]
    }
  ],
  "playlists": [
    {
      "name": "LLHLS ABR",
      "fileName": "abr",
      "options": {
        "webrtcAutoAbr": true,
        "hlsChunklistPathDepth": 0
      },
      "renditions": [
        {
          "name": "input1",
          "video": "input1_video",
          "audio": "input1_audio"
        },
        {
          "name": "input2",
          "video": "input2_video",
          "audio": "input2_audio"
        }
      ]
    }
  ]
}

Responses

201 Created

A stream has been created.

Header

Content-Type: application/json

Body

{
    "message": "Created",
    "statusCode": 201
}

# statusCode
    Same as HTTP Status Code
# message
    A human-readable description of the response code

400 Bad Request

Invalid request. Body is not a Json Object or does not have a required value

401 Unauthorized

Authentication required

Header

WWW-Authenticate: Basic realm=”OvenMediaEngine”

Body

{
    "message": "[HTTP] Authorization header is required to call API (401)",
    "statusCode": 401
}

404 Not Found

The given vhost name or app name could not be found.

Body

{
    "statusCode": 404,
    "message": "Could not find the application: [default/non-exists] (404)"
}

409 Conflict

A stream with the same name already exists

502 Bad Gateway

Failed to pull provided URL

500 Internal Server Error

Unknown error

Get Channel Info

Get detailed information of multiplex channel. It also provides information about the currently playing program and item.

Request

GET /v1/vhosts/{vhost}/apps/{app}/multiplexChannels/{channel name}

Header

Authorization: Basic {credentials}

# Authorization
    Credentials for HTTP Basic Authentication created with <AccessToken>

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body

{
    "message": "OK",
    "statusCode": 200,
    "response": {
        "state": "Pulling",
        "pullingMessage": "Multiplex Channel : #default#app/stream: Wait for stream input1",
        "outputStream": {
            "name": "stream"
        },
        "playlists": [
            {
                "fileName": "abr",
                "name": "LLHLS ABR",
                "options": {
                    "hlsChunklistPathDepth": 0,
                    "webrtcAutoAbr": true
                },
                "renditions": [
                    {
                        "audio": "input1_audio",
                        "name": "input1",
                        "video": "input1_video"
                    },
                    {
                        "audio": "input2_audio",
                        "name": "input2",
                        "video": "input2_video"
                    }
                ]
            }
        ],
        "sourceStreams": [
            {
                "name": "input1",
                "trackMap": [
                    {
                        "bitrateConf": 128000,
                        "newTrackName": "input1_audio",
                        "sourceTrackName": "bypass_audio"
                    },
                    {
                        "bitrateConf": 5000000,
                        "framerateConf": 30,
                        "newTrackName": "input1_video",
                        "sourceTrackName": "bypass_video"
                    }
                ],
                "url": "stream://default/app/input1"
            },
            {
                "name": "input2",
                "trackMap": [
                    {
                        "bitrateConf": 128000,
                        "newTrackName": "input2_audio",
                        "sourceTrackName": "bypass_audio"
                    },
                    {
                        "bitrateConf": 1000000,
                        "framerateConf": 30,
                        "newTrackName": "input2_video",
                        "sourceTrackName": "bypass_video"
                    }
                ],
                "url": "stream://default/app/input2"
            }
        ]
    }
}

401 Unauthorized

Authentication required

Header

WWW-Authenticate: Basic realm=”OvenMediaEngine”

Body

{
    "message": "[HTTP] Authorization header is required to call API (401)",
    "statusCode": 401
}

404 Not Found

The given vhost name or app name could not be found.

Header

Content-Type: application/json

Body

{
    "statusCode": 404,
    "message": "Could not find the application or stream (404)"
}

Delete Channel

Delete Multiplex Channel

Request

DELETE /v1/vhosts/{vhost}/apps/{app}/multiplexChannels/{channel name}

Header

Authorization: Basic {credentials}

# Authorization
    Credentials for HTTP Basic Authentication created with <AccessToken>

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body

{
	"statusCode": 200,
	"message": "OK",
}


# statusCode
	Same as HTTP Status Code
# message
	A human-readable description of the response code

401 Unauthorized

Authentication required

Header

WWW-Authenticate: Basic realm=”OvenMediaEngine”

Body

{
    "message": "[HTTP] Authorization header is required to call API (401)",
    "statusCode": 401
}

404 Not Found

The given vhost name or app name could not be found.

Header

Content-Type: application/json

Body

{
    "message": "[HTTP] Could not find the stream: [default/#default#app/stream] (404)",
    "statusCode": 404
}