RAS API Documentation

Authentication

All API requests require an API key passed in the x-api-key header. Your API key is provided when your integration is set up.

If the key is missing, malformed, or invalid, the API returns 401 Unauthorized.

Header

Name	Type	Description
x-api-key	string required	Your assigned API key

Try It Configuration

Enter your API key and base URL to use the interactive "Try It" panels below.

API Key

Base URL

Example Header

x-api-key: your-api-key-here

Base URL

Each range location has its own subdomain. Replace {rangename} with your assigned location name.

Your Base URL https://{rangename}.rangesystems.com/api/

Example

https://ras.rangesystems.com/api/
https://skokie.rangesystems.com/api/
https://shanks.rangesystems.com/api/

Get Bay Data

GET /api/read

Retrieves the current state of all bays at your range. Returns an array of bay objects with their current mode, error status, equipment type, and last update timestamp.

Rate limit — not a live feed /api/read is rate-limited to 1 request per 10 seconds per API key. Calls beyond that return 429 Too Many Requests — treat a 429 as a signal to back off, not retry immediately. Use this endpoint for spot-checks and reconciliation. For a continuous live view of bay state, use the Bay-Status Heartbeat instead — RAS pushes every bay's state to your endpoint about once per minute, which is fresher on average than polling and adds no request overhead on your side.

Response Fields

Field	Type	Description
BayNumber	integer	Bay identifier (1-30 depending on range)
ModeType	integer	Current bay mode. See ModeType Enum
ErrorId	integer	Current error state. See ErrorID Enum
EquipmentType	string	Equipment model (e.g. "DR1600", "NanoTee", "NanoVending")
DataTimeStamp	string	ISO 8601 timestamp of last data update

Send Request

GET request to /api/read — no body required.

Response 200

{
  "BayData": [
    {
      "BayNumber": 1,
      "ModeType": 2,
      "ErrorId": 0,
      "EquipmentType": "DR1600",
      "DataTimeStamp": "2025-11-03T17:00:49Z"
    },
    {
      "BayNumber": 2,
      "ModeType": 1,
      "ErrorId": 0,
      "EquipmentType": "NanoTee",
      "DataTimeStamp": "2025-11-03T17:00:48Z"
    }
  ]
}

Start Bay

POST /api/write?guid={unique-guid}

Starts a session on a bay. You can start a time-based session (set TotalTime in minutes with TotalBalls=999) or a ball-based session (set TotalBalls with TotalTime=0).

Each request must include a unique guid query parameter to prevent duplicate commands.

Query Parameters

Name	Type	Description
guid	string required	Unique identifier (GUID) for this command

Body Parameters

Name	Type	Description
BayId	integer required	Bay number (1-30 depending on range)
Active	boolean required	Set to `true` to start
TotalBalls	integer required	Ball count for session. Use 999 for timed sessions
TotalTime	integer required	Minutes for session. Use 0 for ball-based sessions
Sender	string required	Your integration name identifier

Send Request

BayId

TotalBalls

TotalTime (minutes)

Comments (optional)

60 Minute Session

{
  "BayId": 1,
  "Active": true,
  "TotalBalls": 999,
  "TotalTime": 60,
  "Sender": "InRange"
}

100 Ball Session

{
  "BayId": 1,
  "Active": true,
  "TotalBalls": 100,
  "TotalTime": 0,
  "Sender": "YGB"
}

Stop Bay

POST /api/write?guid={unique-guid}

Stops an active session on a bay. Set Active to false and both TotalBalls and TotalTime to 0.

Each request must include a unique guid query parameter.

Body Parameters

Name	Type	Description
BayId	integer required	Bay number to stop
Active	boolean required	Set to `false` to stop
TotalBalls	integer	Set to 0
TotalTime	integer	Set to 0
Sender	string required	Your integration name identifier

Send Request

BayId

Comments (optional)

Stop Bay 1

{
  "BayId": 1,
  "Active": false,
  "TotalBalls": 0,
  "TotalTime": 0,
  "Sender": "InRange"
}

Edit Bay

POST /api/edit

Modify an active session without stopping and restarting the bay. Use this to extend or reduce time, or update the ball count on a running session. For a time-based edit, set TotalTime (minutes) and send TotalBalls=999; for a ball-based edit, set TotalBalls with TotalTime=0.

Body Parameters

Name	Type	Description
BayId	integer required	Bay number to edit
TotalBalls	integer required	Updated total balls. Use `999` for timed sessions (send alongside `TotalTime`)
TotalTime	integer required	Updated total minutes (0 for ball-based sessions)

Error Responses

Error	Description
`Bay X not found`	The specified bay does not exist
`No active session on this bay`	The bay is not currently running
`Invalid numeric parameters`	TotalBalls or TotalTime is not a valid number

Send Request

BayId

TotalBalls

TotalTime (minutes)

Extend to 90 Minutes

{
  "BayId": 1,
  "TotalBalls": 999,
  "TotalTime": 90
}

Update to 100 Balls

{
  "BayId": 2,
  "TotalBalls": 100,
  "TotalTime": 0
}

Success Response

{
  "success": true
}

Batch Start Bays

POST /api/batch

Start multiple bays in a single request. Send an array of command objects in the commands field. Each command follows the same format as the individual Start Bay endpoint.

Body Parameters

Name	Type	Description
commands	array required	Array of command objects (same fields as Start/Stop Bay)

Send Request

Request Body (JSON)

Batch Start - 60 Min Sessions

{
  "commands": [
    {
      "BayId": "10",
      "Active": true,
      "TotalBalls": "999",
      "TotalTime": "60",
      "Sender": "inrange"
    },
    {
      "BayId": "11",
      "Active": true,
      "TotalBalls": "999",
      "TotalTime": "60",
      "Sender": "inrange"
    }
  ]
}

Batch Stop Bays

POST /api/batch

Stop multiple bays in a single request. Set Active to false for each command in the array.

Send Request

Request Body (JSON)

Batch Stop Bays 10 & 11

{
  "commands": [
    {
      "BayId": "10",
      "Active": false,
      "TotalBalls": "0",
      "TotalTime": "0",
      "Sender": "inrange"
    },
    {
      "BayId": "11",
      "Active": false,
      "TotalBalls": "0",
      "TotalTime": "0",
      "Sender": "inrange"
    }
  ]
}

Bay-Status Heartbeat

POST (your endpoint)

Unlike the endpoints above (which you call on RAS), the heartbeat is a push from RAS to your system. When enabled for a venue, the on-site RAS controller POSTs a snapshot of every bay's state to a URL you host, roughly once per minute. Use it to keep your dashboard live without polling and to detect when a venue's controller goes offline (heartbeats simply stop arriving). This is the intended live feed — polling /api/read at high frequency is rate-limited (1 request per 10 seconds) and returns 429 beyond that.

What you provide to RAS 1. A heartbeat URL that accepts a POST. RAS appends your venue identifier to the path so you know which site each beat is for — e.g. https://api.youapp.com/v1/ras/heartbeat/{your-venue-id} 2. The x-api-key value RAS should send on each request (optional but recommended).

RAS configures this per venue on our side — there is nothing for you to call to turn it on. Heartbeats begin once the venue's on-site controller is running and connected, and are best-effort (failed POSTs are retried with backoff; persistent failures restart the sender).

Payload Fields (per bay)

Field	Type	Description
BayNumber	integer	Bay identifier
ModeType	integer	Current bay mode. See ModeType Enum
OperationMode	integer	Operating mode of the bay
ErrorId	integer	Active error code. See ErrorID Enum
EquipmentType	string	Dispenser/equipment type at the bay

Request RAS sends to you

POST https://api.youapp.com/v1/ras/heartbeat/<your-venue-id>
x-api-key: <agreed key>
Content-Type: application/json

[
  {
    "BayNumber": 1,
    "ModeType": 4,
    "OperationMode": 0,
    "ErrorId": 0,
    "EquipmentType": "NanoDispenser"
  }
]

ModeType Enum

The ModeType field in the bay data response indicates the current operating state of a bay.

Value	State	Description
1	Ball Rental	Bay is dispensing a ball-count session
2	Available	Bay is idle and ready for use
3	Freeplay	Bay is in unlimited freeplay mode
4	Time Rental	Bay is dispensing a time-based session
5	Checked In	Bay has been checked in by a customer
6	Checked Out	Bay has been checked out
7	Error	Bay has an equipment error (see ErrorID)
9	Manual Mode	Bay is under manual operator control
10	No Response	Bay is not communicating with the system

ErrorID Enum

Error codes depend on the equipment type installed at the bay.

AutoTee Errors

ErrorID	Description
0	No Error
1	Tee Sensor
2	Bottom Sensor
3	Chute Sensor
9	Tee And Chute Sensor
10	Motor Sensor
11	Bottom And Chute Sensor
12	Tee And Bottom Sensor

DR1600 Errors

ErrorID	Description
0	No Error
4	Drum Sensor
5	Club Sensor
6	Low Balls
7	Low Balls And Drum Sensor
8	Low Balls And Club Sensor

HTTP Response Codes

Code	Description
200	Request processed successfully
401	Missing, malformed, or invalid API key
403	Incorrect range name or API key mismatch
429	Rate limit exceeded - reduce request frequency. `/api/read` is limited to 1 request per 10 seconds; use the heartbeat for a live view
503	Unexpected spike in API traffic - retry after a short delay

Need help? Contact api@rangesystems.com

Range Automation Systems — API Documentation