RAS RAS

Help Center

Dashboard API Docs

Getting Started

Welcome to the RAS Integration Help Center. This guide covers everything you need to know about using the Integration Dashboard and REST API.

What is the Integration Dashboard?

The Integration Dashboard is a web-based tool for third-party integrators to monitor and manage bay commands sent to Range Automation Systems venues. It provides real-time command logs, KPI summaries, and anomaly detection across all your connected venues.

Quick Start

  1. Sign in with your integrator name and API key on the login screen.
  2. Select a venue from the dropdown in the controls bar to load command data.
  3. Review command logs in the table, use filters to narrow results, and click KPI cards to filter by action type.
  4. Check for anomalies in the Anomalies panel that appears when unusual patterns are detected.
Tip
Bookmark the API Documentation page for interactive Try It panels where you can test API endpoints directly from your browser.

Dashboard Guide

A walkthrough of the dashboard interface and its components.

Header

The header bar displays the RAS logo, your integrator name (shown as a badge), and links to API Docs, Help, theme toggle (light/dark mode), and Sign Out.

Controls Bar

The controls bar sits below the header and provides the following filters:

Control Description
Venue Select which venue to view command logs for. Only venues assigned to your integrator account are shown.
Period Time window for data: 1 hour, 6 hours, 12 hours, 24 hours (default), 48 hours, or 7 days.
Bay Filter commands to a specific bay number. Leave empty to show all bays.
Sender Filter by the system or user that sent the command. Leave empty to show all senders.
Refresh Reload data from the API with current filter settings.

Summary KPI Cards

Six cards display aggregate counts for the selected period:

  • Total Commands — All commands in the selected period
  • Starts — Bay start commands (green)
  • Stops — Bay stop commands (orange)
  • Edits — Bay edit commands (blue)
  • Reads — Bay read commands (purple)
  • Anomalies — Detected anomalies (red)
Tip
Click any KPI card to filter the command log table to only that action type. Click again to clear the filter.

Command Logs

Understanding the command log table and its columns.

Column Description
Timestamp Date and time the command was received, displayed in your local timezone. Click the header to toggle sort order.
Bay The bay number the command targets.
Action The type of command sent. See action types below.
Balls Number of balls dispensed (for START/EDIT commands).
Time (min) Duration in minutes allocated to the session (for START/EDIT commands).
Endpoint The API endpoint that processed the command (e.g., /api/write, /api/read).
Sender The integrator or system that sent the command.
Comments Optional text included with the command for tracking purposes.
Command ID Unique identifier (GUID) for the command, useful for support and debugging.

Action Types

Action Description API Endpoint
START Activates a bay with specified balls and time allocation. POST /api/write with Active: true
STOP Deactivates a bay, ending the current session. POST /api/write with Active: false
EDIT Modifies balls or time on an active bay without restarting. POST /api/edit
READ Reads the current state of all bays at the venue. GET /api/read

Filtering & Search

How to narrow down command log results.

Venue Selector

The venue dropdown shows all venues assigned to your integrator account. Select a venue to load its command data. The dashboard remembers your last selected venue between sessions.

Time Period

Choose a time window to control how far back to retrieve commands. Longer periods may take slightly longer to load. The default is 24 hours.

Bay Filter

Type a bay number to filter the command log to commands targeting that specific bay. Leave empty to see all bays. The filter applies as you type.

Sender Filter

Type a sender name to filter commands to those sent by a specific integrator or system. This is useful when multiple systems are sending commands to the same venue.

KPI Card Filtering

Click any of the six summary cards at the top of the dashboard to filter the table to only that command type. For example, clicking the "Starts" card will show only START commands. Click the same card again to clear the filter and show all commands.

Tip
Filters can be combined. For example, select a venue, set the period to 7 days, type a bay number, and click the "Anomalies" card to see all anomalies for that specific bay over the last week.

Anomaly Detection

Understanding and responding to detected anomalies in command patterns.

What Are Anomalies?

The dashboard automatically analyzes command patterns and flags unusual activity. Anomalies may indicate integration bugs, unexpected behavior, or configuration issues that need attention.

Anomaly Panel

When anomalies are detected, a red panel appears above the command log table showing a summary count and list of detected issues. Click any anomaly row to view full details in a modal dialog.

Severity Levels

Severity Description Action Required
High Critical issues such as rapid duplicate commands, start without stop, or commands to non-existent bays. Investigate immediately. These may indicate a bug in your integration.
Medium Unusual patterns such as high command frequency, unusual time/ball values, or repeated edits. Review at your convenience. May indicate suboptimal integration logic.
Low Minor observations such as commands at unusual hours or minor timing variations. Informational only. No immediate action needed.

Anomaly Details

Click an anomaly row to open a detail modal showing:

  • Title — Short description of the anomaly type
  • Severity — High, Medium, or Low
  • Description — Detailed explanation of what was detected
  • Suggested Fix — Recommended steps to resolve the issue

API Overview

Overview of the RAS REST API for programmatic bay control.

The RAS API allows integrators to programmatically read bay states and send commands (start, stop, edit) to bays at connected venues. All communication uses HTTPS with API key authentication.

Available Endpoints

Method Endpoint Description
GET /api/read Retrieve current state of all bays at a venue
POST /api/write Start or stop a bay session
POST /api/edit Modify balls or time on an active bay
POST /api/batch Send multiple start or stop commands in a single request
Tip
Visit the API Documentation page for detailed request/response schemas and interactive Try It panels for each endpoint.

Authentication

How authentication works for the dashboard and API.

Dashboard Login

Sign in using your integrator name and API key. These credentials are provided by Range Automation Systems when your integrator account is provisioned.

API Authentication

All API requests must include your API key in the x-api-key header. Requests without a valid key will receive a 401 Unauthorized or 403 Forbidden response.

HTTP Header
x-api-key: YOUR_API_KEY

Example Authenticated Request

cURL
curl -X GET "https://YOUR_BASE_URL/api/read" \
  -H "x-api-key: YOUR_API_KEY"
Important
Never share your API key in public repositories, client-side code, or unsecured channels. Treat it like a password.

API Keys

Managing your API keys and security best practices.

Obtaining Your API Key

API keys are provisioned by Range Automation Systems during integrator onboarding. Each integrator receives a unique key tied to their account and venue assignments.

Key Rotation

If you need to rotate your API key (e.g., suspected compromise), contact Range Automation Systems support. A new key will be issued and the old key will be revoked.

Security Best Practices

  • Store securely — Keep your API key in environment variables or a secrets manager. Never hardcode it in source code.
  • Server-side only — Always make API calls from your backend server, never from client-side JavaScript or mobile apps.
  • Monitor usage — Regularly review command logs in the dashboard to detect any unauthorized usage.
  • Report compromises — If you suspect your key has been compromised, contact support immediately for rotation.

Making API Calls

Common API patterns with request and response examples.

Reading Bay State

Use GET /api/read to retrieve the current state of all bays at a venue.

Request
GET /api/read
x-api-key: YOUR_API_KEY

Starting a Bay

Use POST /api/write with Active: true to start a bay session. Include a unique GUID as a query parameter for idempotency.

Request
POST /api/write?guid=UNIQUE_GUID
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "BayId": 1,
  "Active": true,
  "TotalBalls": 100,
  "TotalTime": 60,
  "Sender": "YourIntegrator",
  "Comments": "Session started via API"
}

Stopping a Bay

Use POST /api/write with Active: false to stop an active bay.

Request
POST /api/write?guid=UNIQUE_GUID
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "BayId": 1,
  "Active": false,
  "TotalBalls": 0,
  "TotalTime": 0,
  "Sender": "YourIntegrator",
  "Comments": "Session ended"
}

Editing an Active Bay

Use POST /api/edit to modify the balls or time on an active bay without restarting the session.

Request
POST /api/edit
Content-Type: application/json
x-api-key: YOUR_API_KEY

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

Batch Operations

Use POST /api/batch to start or stop multiple bays in a single request. This is more efficient than sending individual commands.

Tip
Always include a unique guid query parameter on write requests. This ensures idempotency — if a request is retried due to a network error, the command won't be executed twice.

Heartbeat

A live, push-based feed of bay status from RAS to your system.

The API endpoints above are pull — your system calls RAS. The heartbeat is the reverse: when enabled for a venue, the on-site RAS controller pushes a snapshot of every bay's state to a URL you host, about once per minute. It's the recommended way to keep a live view without polling, and it doubles as an offline detector — if heartbeats stop arriving, that venue's controller is down.

Don't poll for live data
/api/read is rate-limited to 1 request per 10 seconds per API key — requests beyond that return 429 Too Many Requests. If you need bay state more often than that, the heartbeat is the answer: it's pushed to you every minute with no request overhead, and it's fresher on average than polling. Keep /api/read for spot-checks and reconciliation.

What you provide

ItemDescription
Heartbeat URL An endpoint that accepts a POST. RAS appends your venue identifier to the path so each beat is attributable to a site — e.g. https://api.youapp.com/v1/ras/heartbeat/{your-venue-id}
x-api-key A key RAS sends on every heartbeat request so you can authenticate it (recommended).

Payload

Each POST body is a JSON array of bay objects: BayNumber, ModeType, OperationMode, ErrorId, and EquipmentType. The same ModeType and ErrorID enums from the API apply.

Enabling it
RAS configures the heartbeat per venue on our side — there is nothing for you to call to switch it on. Just send your venue ID, heartbeat URL, and key to your RAS contact. Heartbeats begin once the venue's on-site controller is online, and are best-effort (failed POSTs retry with backoff).

Troubleshooting

Common issues and how to resolve them.

Login Issues

Problem Solution
"Invalid credentials" error Verify your integrator name and API key are correct. Names are case-sensitive. Check for leading or trailing spaces.
Login page won't load Check your internet connection and try clearing your browser cache. Ensure you're using a modern browser (Chrome, Firefox, Edge, Safari).
Session expired For security, sessions expire after a period of inactivity. Simply sign in again with your credentials.

Dashboard Issues

Problem Solution
No venues in dropdown Your integrator account may not have any venues assigned. Contact Range Automation Systems to verify your venue assignments.
No data showing for venue Ensure the selected time period covers when commands were sent. Try expanding to "Last 7 days". If still empty, no commands have been sent in that period.
Data not refreshing Click the Refresh button in the controls bar. If data is still stale, try signing out and signing back in.

API Errors

Status Code Meaning Resolution
401 Unauthorized — Missing or invalid API key Verify the x-api-key header is present and contains a valid key.
403 Forbidden — Key is valid but not authorized for this venue or action Check that your API key has permission for the target venue. Contact support if needed.
400 Bad Request — Invalid request body or parameters Check the request body matches the expected schema. Refer to the API Docs.
429 Too Many Requests — Rate limit exceeded Reduce your request frequency. Implement exponential backoff in your integration.
500 Internal Server Error Retry after a few seconds. If persistent, contact Range Automation Systems support.

Frequently Asked Questions

Answers to common questions about the Integration Dashboard and API.

How often does the dashboard data refresh?

Data is fetched from the API each time you select a venue, change a filter, or click Refresh. There is no automatic polling — you control when data is loaded.

What timezone are timestamps displayed in?

Timestamps in the command log are converted to your browser's local timezone. The API stores all timestamps in UTC internally.

Are there rate limits on the API?

Yes. API Gateway enforces rate limits per API key. If you exceed the limit, you'll receive a 429 Too Many Requests response. Implement retry logic with exponential backoff in your integration.

Can I have multiple API keys?

Each integrator account is issued one API key. If you need separate keys for development and production, contact Range Automation Systems to discuss options.

What happens if I send a duplicate command?

Use the guid query parameter on write requests to ensure idempotency. If the same GUID is sent twice, the second request will be treated as a duplicate and won't execute again.

How do I request access to additional venues?

Contact Range Automation Systems support with the venue names you need access to. Venue assignments are managed at the account level.

Is there a sandbox or test environment?

Contact Range Automation Systems to request access to a sandbox environment for development and testing. This lets you test your integration without affecting production venues.

How do I contact support?

For technical issues, integration questions, or account management, contact Range Automation Systems at support@rangesystems.com.

Need More Help?
If your question isn't answered here, check the API Documentation for detailed endpoint specifications, or contact support@rangesystems.com.
Range Automation Systems — Integration Help Center