API Documentation v1.0

Integrate WinScale truck scale data into your applications with our powerful RESTful API. Access real-time weights, historical data, and receive webhooks for scale events.

Introduction

The WinScale API provides programmatic access to your truck scale data. Use it to integrate weight data into your ERP systems, build custom dashboards, automate ticketing, or create alerts based on scale events.

Base URL

https://api.cloud-scale.us/v1

Key Features

• Real-time weight data — Get current weight from any connected scale
• Historical records — Query weight history with flexible filtering
• Webhooks — Receive push notifications for scale events
• WebSocket streaming — Subscribe to live weight updates
• Multi-scale support — Manage all your scales from one API

Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header of each request.

Authorization: Bearer YOUR_API_KEY

Obtaining API Keys

API keys are generated from your Cloud-Scale dashboard. Enterprise customers can create multiple keys with different permission levels:

• Read-only — Access weight data and history
• Read-write — Full access including tare operations
• Admin — Manage scales, users, and webhooks

Rate Limits

API requests are rate-limited to ensure fair usage and system stability.

Rate limit headers are included in every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1706572800

Error Handling

The API uses standard HTTP status codes and returns errors in a consistent JSON format.

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or expired",
    "status": 401
  }
}

Scales

Manage and retrieve information about your connected scales.

{
  "scales": [
    {
      "id": "scale_01HV8XJKM2",
      "name": "Truck Scale 1",
      "location": "Main Entrance",
      "protocol": "fairbanks_6011",
      "status": "online",
      "last_weight": {
        "value": 42350,
        "unit": "lb",
        "stable": true,
        "timestamp": "2026-01-30T00:30:00Z"
      }
    }
  ],
  "total": 1
}

Weights

Access real-time weight data from your scales.

{
  "scale_id": "scale_01HV8XJKM2",
  "weight": {
    "gross": 42350,
    "tare": 0,
    "net": 42350,
    "unit": "lb",
    "stable": true,
    "motion": false,
    "overload": false
  },
  "timestamp": "2026-01-30T00:35:12Z"
}

{
  "tare_value": 15000  // Optional: manual tare value in lb
}

Weight History

Query historical weight records with flexible filtering options.

{
  "records": [
    {
      "id": "rec_01HV8Y2KNP",
      "weight": 42350,
      "unit": "lb",
      "stable": true,
      "timestamp": "2026-01-30T00:30:00Z",
      "metadata": {
        "plate": "ABC-1234",  // If LPR enabled
        "ticket_id": "TKT-00123"
      }
    }
  ],
  "total": 156,
  "limit": 100,
  "offset": 0
}

System Status

Monitor the health and status of your WinScale deployment.

{
  "status": "operational",
  "scales": {
    "total": 3,
    "online": 3,
    "offline": 0
  },
  "api_version": "1.0",
  "server_time": "2026-01-30T00:40:00Z"
}

Webhooks

Receive real-time notifications when scale events occur. Configure webhook endpoints from your dashboard or via API.

Available Events

Webhook Payload

{
  "event": "weight.stable",
  "timestamp": "2026-01-30T00:45:00Z",
  "data": {
    "scale_id": "scale_01HV8XJKM2",
    "scale_name": "Truck Scale 1",
    "weight": {
      "gross": 78450,
      "unit": "lb",
      "stable": true
    }
  },
  "webhook_id": "whk_01HV8Y5MPQ"
}

{
  "url": "https://your-server.com/webhook",
  "events": ["weight.stable", "scale.offline"],
  "scale_ids": ["scale_01HV8XJKM2"],  // Optional: filter by scales
  "secret": "your_webhook_secret"  // For signature verification
}

Real-time Streaming

Subscribe to live weight updates via WebSocket for real-time applications.

WebSocket Connection

wss://api.cloud-scale.us/v1/stream?token=YOUR_API_KEY

Subscribe to Scale

// Send after connection
{
  "action": "subscribe",
  "scale_ids": ["scale_01HV8XJKM2"]
}

// Incoming weight updates
{
  "type": "weight",
  "scale_id": "scale_01HV8XJKM2",
  "weight": 42380,
  "unit": "lb",
  "stable": false,
  "timestamp": "2026-01-30T00:50:00.123Z"
}

Integrations

WinScale API is designed to integrate with your existing systems:

Common Integration Patterns

• ERP Integration — Push weight data to SAP, Oracle, QuickBooks
• Ticketing Systems — Auto-generate scale tickets with weight + timestamp
• Dispatch Software — Real-time weight visibility for dispatchers
• Custom Dashboards — Build internal monitoring tools
• Alert Systems — Trigger notifications on weight thresholds

SDKs & Libraries

Official client libraries for popular languages (coming soon):

Code Examples

Python — Get Current Weight

import requests

API_KEY = "your_api_key"
SCALE_ID = "scale_01HV8XJKM2"

response = requests.get(
    f"https://api.cloud-scale.us/v1/scales/{SCALE_ID}/weight",
    headers={"Authorization": f"Bearer {API_KEY}"}
)

data = response.json()
print(f"Current weight: {data['weight']['gross']} {data['weight']['unit']}")

C# — Get Current Weight

using System.Net.Http;
using System.Net.Http.Headers;

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = 
    new AuthenticationHeaderValue("Bearer", "your_api_key");

var response = await client.GetAsync(
    "https://api.cloud-scale.us/v1/scales/scale_01HV8XJKM2/weight"
);

var json = await response.Content.ReadAsStringAsync();
Console.WriteLine(json);

JavaScript — WebSocket Streaming

const ws = new WebSocket('wss://api.cloud-scale.us/v1/stream?token=YOUR_API_KEY');

ws.onopen = () => {
    ws.send(JSON.stringify({
        action: 'subscribe',
        scale_ids: ['scale_01HV8XJKM2']
    }));
};

ws.onmessage = (event) => {
    const data = JSON.parse(event.data);
    console.log(`Weight: ${data.weight} ${data.unit}`);
};

Support

Need help with the API? We're here for you.

• Email: api-support@cloud-scale.us
• Enterprise Support: Contact your dedicated account manager
• Status Page: status.cloud-scale.us