REST API and UI Settings

Stamp comes with a fully functional REST API that allows easier integration with external services. To enable the REST API, you need to set stamp.api.enabled to true.

You can set the port on which Stamp listens to requests with the stamp.api.port paramter. If not set, by default it is 4567.

The REST API has preconfigured CORS filter so that it will respond to CORS preflight requests (OPTIONS) and will allow access from any server.

Please note that without SSL enabled in Stamp exposing the UI and the REST API to public internet is a security risk.

stamp.api.enabled

Set to true to enable REST API and UI. Default: false

stamp.api.port

The port for the UI and the REST API. Default: 4567

stamp.rest.api.authentication

Set to false if you want to allow talking to the API without any authentication. Currently Stamp comes with a session based authentication mechanism that is used by the UI’s login form and an optionally configurable HTTP Basic authentication that has to be switched on. Default: true

stamp.api.ssl.enabled

Set to true to enable SSL support in Stamp. When SSL is enabled, Stamp makes an attempt to find the keystore path and password from the VHost configuration in which the application is running. This means that if you have SSL set up in Wowza for streaming, Stamp should be able to pick up the same configuration automatically. Default: false

The logs should show clearly if SSL is used or not:

Started Stamp UI on https://localhost:4567 with SSL enabled

or

Started Stamp UI on http://localhost:4567 without SSL enabled

stamp.api.auth.basic

Enables HTTP Basic authentication on the API. Please note that this is only secure if used in conjuction with SSL.

Default: false

stamp.api.auth.basic.user

This gives you the ability to define a single user that can use the UI or the REST API additionally to the normal Wowza admin users

stamp.api.auth.basic.password

This gives you the ability to define a single user password that can use the UI or the REST API additionally to the normal Wowza admin users

REST API Endpoints

The REST API of Stamp is documented using OpenAPI specification using Swagger. You can find the explorable, interactive API documentation here:

http://streamtoolbox.com/swagger-ui/?url=http://streamtoolbox.com/api-docs/stamp.json

You can also find the API on SwaggerHub where you can download generated clients in various languages:

https://app.swaggerhub.com/apis/jantekb/Stamp/2020.04.13

The documentation generated from the above swagger is also available as static document.

POST /clamp/login

login

Query Parameters

  • username (string) – the username for login

  • password (string) – the password for login - please note that this is only safe is Clamp is configured to use SSL

Status Codes
GET /clamp/logout

logout

Status Codes

  • 200 OK – logout successful

POST /clamp/instructions

Send in a new single overlay instruction or an array of overlay instructions to Clamp

Status Codes

  • 200 OK – instruction accepted. The id or the array of ids are returned of the instructions

DELETE /clamp/instructions

Remove all instructions immediately on a single or all streams

Query Parameters

  • scheduleStream (string) – The name of the stream on which all the overlays need to be removed. If omitted, then they are removed on all streams

Status Codes

  • 200 OK – Remove successful

GET /clamp/instructions/{id}

Load a single instruction by id

Parameters

  • id (string) –

Status Codes
DELETE /clamp/instructions/{id}

Remove a single instruction by id

Parameters

  • id (string) –

Status Codes

  • 200 OK – Instruction removed successfully

  • 404 Not Found – Instruction not found for removal

POST /clamp/instructions/{id}

Edit an already submitted instruction

Parameters

  • id (string) –

Status Codes
GET /clamp/instructions/active

Get all instructions currently active on any stream

Status Codes

  • 200 OK – The array containing the currently active instructions

GET /clamp/instructions/waiting

Get all instructions currently waiting to be scheduled at some point

Status Codes

  • 200 OK – The array containing the currently waiting instructions

POST /clamp/instructions/batch

Atomic update to create/edit/remove a batch of caption instructions

Status Codes

  • 200 OK – A map with the same keys and the value is true or false depending on the operation outcome for that id

POST /clamp/instructions/overlays

Turn Clamp overlays on or off completely on specified streams without deleting instructions

Status Codes

  • 200 OK – The result object of the modification