NAV Navbar
shell http
  • Introduction
  • Requests
  • Data
  • Errors
  • Introduction

    This documents an HTTP based API for basic control of ProPresenter-Scoreboard.

    Requests

    Scheme

    Requests may be made over HTTP or HTTPS depending on your network settings in ProPresenter-Scoreboard.

    Prefix

    All request paths are prefixed with /api/0 in addition to the standard URL components for the scheme (https), host, and port.

    For an end point with the path /data/data, the full request would be:

    GET https://localhost:8080/api/0/data/data

    Authentication

    API Access Request:

    // HTTP
    GET /api/0/data/playlists HTTP/1.1
    Host: localhost:8080
    Content-Type: application/json
    
    // HTTPS 
    GET /api/0/data/playlists HTTP/1.1
    Host: localhost:8080
    Content-Type: application/json
    Authorization: Bearer <your unique key here>
    
    // HTTPS
    curl -H "Authorization: Bearer <your unique key here>" -X GET https://localhost:8080/api/0/data/scores -k
    

    Access to the API is controlled via API keys. Keys can be managed in ProPresenter-Scoreboard preferences.

    The API expects the API key to be passed with all requests via an Authorization header like the following:

    Authorization: Bearer <your unique key here>

    JSON

    POST /api/0/opacity/layer/0 HTTP/1.1
    Host: localhost:8080
    Content-Type: application/json
    
    { "value": 0.5 }
    
     

    Some POST requests can take JSON data as a parameter; these are noted by the sections in the documentation that contain a 'Request Body'. Our API conforms to the JSON 1.0 Specification

    HTTP

    If JSON is needed for an HTTP request, the folowing should be included in the request:

    { "<requestBodyKey>": <requestBodyValue> }

    CURL

    If JSON is needed for a cURL request, the following should be included in the request:

    -d '{ "<requestBodyKey>":<requestBodyValue> }' -H "Content-Type: application/json"

    Data

    Each sport contains its own scoring properties. Custom sports will be user defined.

    Scores

    Example Request:

    GET /api/0/data/scores HTTP/1.1
    Host: localhost:8080
    Content-Type: application/json
    
    curl -X GET http://localhost:8080/api/0/data/scores -k
    

    Each return value contians a UUID, sportMode and Version number...

    "uuid" : "<unique identifier>",

    "version" : "1.0",

    "sportMode" : "<sport name>"

    Along with the following properties that define each sport:

    JSON response:

    Australian Football

    {
      "sportMode" : "AustralianFootball",
      "quarter" : "1",
      "sportMode" : "Custom",
      "team1Behinds" : "2",
      "team1Goals" : "3",
      "team1Name" : "Atlanta",
      "team1Score" : "20",
      "team2Behinds" : "3",
      "team2Goals" : "4",
      "team2Name" : "Boston",
      "team2Score" : "27"
    }
    

    Baseball

    {
      "sportMode" : "Baseball",
      "balls" : "1",
      "errors" : "1",
      "hits" : "5",
      "inning" : "5",
      "outs" : "0",
      "period" : "1",
      "possession" : 1,
      "runs" : "2",
      "strikes" : "0"
      "topBottom" : "T"
      "teamOneRuns" : "3"
      "teamOneErrors" : "2"
      "teamOneHits" : "4"
      "teamOneLineScore1" : "0"
      "teamOneLineScore2" : "0"
      "teamOneLineScore3" : "3"
      "teamOneLineScore4" : ""
      "teamOneLineScore5" : ""
      "teamOneLineScore6" : ""
      "teamOneLineScore7" : ""
      "teamOneLineScore8" : ""
      "teamOneLineScore9" : ""
      "teamTwoRuns" : "4"
      "teamTwoErrors" : "0"
      "teamTwoHits" : "3"
      "teamTwoLineScore1" : "0"
      "teamTwoLineScore2" : "2"
      "teamTwoLineScore3" : "2"
      "teamTwoLineScore4" : ""
      "teamTwoLineScore5" : ""
      "teamTwoLineScore6" : ""
      "teamTwoLineScore7" : ""
      "teamTwoLineScore8" : ""
      "teamTwoLineScore9" : ""
    }
    

    Basketball

    {
      "sportMode" : "Basketball",
      "period" : "2",
      "possession" : 0,
      "sportMode" : "Basketball",
      "team1Bonus1" : false,
      "team1Bonus2" : false,
      "team1Fouls" : "4",
      "team1Score" : "6",
      "team1TimeOuts" : "3",
      "team2Bonus1" : true,
      "team2Bonus2" : true,
      "team2Fouls" : "0",
      "team2Score" : "0",
      "team2TimeOuts" : "3"
    }
    

    Football

    {
      "sportMode" : "Football",
      "ballLocation" : "33",
      "down" : "3",
      "period" : "3",
      "possession" : 1,
      "team1Score" : "24",
      "team1TimeOuts" : "2",
      "team2Score" : "12",
      "team2TimeOuts" : "1",
      "toGo" : "7"
    }
    

    Hockey

    {
      "sportMode" : "Hockey",
      "period" : "2",
      "team1Saves" : "5",
      "team1Score" : "2",
      "team1Shots" : "2",
      "team1TimeOuts" : "3",
      "team2Saves" : "2",
      "team2Score" : "1",
      "team2Shots" : "3",
      "team2TimeOuts" : "3"
    }
    

    Lacrosse

    {
      "sportMode" : "Lacrosse",
      "period" : "2",
      "possession" : 0,
      "team1Saves" : "5",
      "team1Score" : "2",
      "team1Shots" : "2",
      "team1TimeOuts" : "3",
      "team2Saves" : "2",
      "team2Score" : "1",
      "team2Shots" : "3",
      "team2TimeOuts" : "3"
    }
    

    Soccer

    {
      "sportMode" : "Soccer",
      "extraTime" : "3",
      "period" : "2",
      "team1Corner" : "5",
      "team1Saves" : "1",
      "team1Score" : "4",
      "team1Shots" : "3",
      "team1TimeOuts" : "3",
      "team2Corner" : "1",
      "team2Saves" : "0",
      "team2Score" : "1",
      "team2Shots" : "0",
      "team2TimeOuts" : "3"
    }
    

    Tennis

    {
      "sportMode" : "Tennis",
      "currentSet" : 4,
      "period" : "4",
      "possession" : 1,
      "team1Games" : "0",
      "team1Score" : "0",
      "team1Set1" : "2",
      "team1Set2" : "1",
      "team1Set3" : "4",
      "team1Set4" : "0",
      "team1Set5" : " ",
      "team1Set6" : " ",
      "team1Set7" : " ",
      "team1Set8" : " ",
      "team1Set9" : " ",
      "team1Sets" : "2",
      "team1TimeOuts" : "1",
      "team2Games" : "0",
      "team2Score" : "0",
      "team2Set1" : "4",
      "team2Set2" : "0",
      "team2Set3" : "0",
      "team2Set4" : "0",
      "team2Set5" : " ",
      "team2Set6" : " ",
      "team2Set7" : " ",
      "team2Set8" : " ",
      "team2Set9" : " ",
      "team2Sets" : "1",
      "team2TimeOuts" : "3"
    }
    

    Volleyball

    {
      "sportMode" : "Volleyball",
      "currentSet" : 4,
      "period" : "4",
      "possession" : 0,
      "sportMode" : "Volleyball",
      "team1Games" : "2",
      "team1Score" : "0",
      "team1Set1" : "24",
      "team1Set2" : "24",
      "team1Set3" : "21",
      "team1Set4" : "0",
      "team1Set5" : "0",
      "team1Set6" : " ",
      "team1Set7" : " ",
      "team1Set8" : " ",
      "team1Set9" : " ",
      "team1TimeOuts" : "0",
      "team2Games" : "1",
      "team2Score" : "0",
      "team2Set1" : "18",
      "team2Set2" : "21",
      "team2Set3" : "24",
      "team2Set4" : "0",
      "team2Set5" : "0",
      "team2Set6" : " ",
      "team2Set7" : " ",
      "team2Set8" : " ",
      "team2Set9" : " ",
      "team2TimeOuts" : "0"
    }
    

    Custom

    {
      "sportMode" : "Custom",
      "game1" : {
        "possession" : "0",
        "quarter" : "1",
        "team1Goals" : "5",
        "team1Name" : "Atlanta",
        "team1Saves" : "0",
        "team1TimeOuts" : "0",
        "team2Goals" : "1",
        "team2Name" : "Boston",
        "team2Saves" : "0",
        "team2TimeOuts" : "0"
      },
      "game2" : {
        "possession" : "0",
        "quarter" : "1",
        "team1Goals" : "1",
        "team1Name" : "Team 3",
        "team1Saves" : "0",
        "team1TimeOuts" : "0",
        "team2Goals" : "4",
        "team2Name" : "Team 4",
        "team2Saves" : "0",
        "team2TimeOuts" : "0"
      }
    }
    

    In the case of Custom, the score properties are defined by the user. In this example, the score properties are:

    Goals, Saves, Time Outs

    Errors

    The API uses the following error codes:

    Error Code Meaning
    400 Bad Request -- Your request was invalid.
    401 Unauthorized -- Authorization failed.
    403 Forbidden -- The endpoint requested is hidden for administrators only.
    404 Not Found -- The specified endpoint could not be found.
    405 Method Not Allowed -- You tried to access an endpoint with an invalid method.
    500 Internal Server Error -- We had a problem with our server. Try again later.
    503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.