SmartQ.tv Developer API Documentation
Developer API access to venue integrations across ShiftQ, SportsQ, MatriQ, Campaigns, and upcoming OrderBoard and BevQ resources, plus a narrowly scoped MatriQ Auto Scheduler emergency-stop action. Build against location-aware module endpoints, predictable business-date behavior, and production-safe token scopes.
Start with discovery, then follow modules
SmartQ tokens are scoped by module and location. The intended flow is to discover what a token can see, then request only the module resources you need.
Call the locations endpoint first to discover accessible locations, enabled modules, and granted resources.
GET /v1/GROUP_ID/locations
Use the group or location modules endpoint to branch your integration by what is enabled at that venue.
GET /v1/GROUP_ID/LOCATION_ID/modules
Call ShiftQ, SportsQ, MatriQ, Campaigns, OrderBoard, or BevQ endpoints as needed, respecting token scopes.
GET /v1/GROUP_ID/LOCATION_ID/shiftq
curl -H "Authorization: Bearer YOUR_API_TOKEN" \ https://api.smartq.tv/v1/GROUP_ID/locations
Official workspace downloads
SmartQ publishes official Postman collection and environment files for the full Developer API.
Includes discovery, ShiftQ, SportsQ, MatriQ, Campaigns, OrderBoard, and BevQ requests.
/postman/SmartQ-Customer-API.postman_collection.json
Shared variables: baseUrl, token, groupId, locationId, sportsqDate, and businessDate.
/postman/SmartQ-Customer-API.postman_environment.json
Bearer token authentication
Every request must send an API token in the Authorization header. Tokens are customer-specific
and can be limited to a subset of locations and scopes, including optional approval-only control actions.
Authorization: Bearer YOUR_API_TOKEN
Responses can include token scope type, expiry, rate limit, status, and allowed locations so customers can audit what they are using.
Available scopes
Tokens can be granted one or more resource scopes depending on the integration surface needed by the customer.
locations:read
Discover accessible locations, enabled modules, granted endpoints, and refresh metadata.
On demand
sportsq:read
SportsQ guide and event schedule data for the location.
Every 5 minutes
shiftq:read
Covers ShiftQ overview, sales, labor, kitchen, clock-ins, POS menu, employees, reservations, POS reservations alias, and group leaderboard resources.
Sales, labor, kitchen ticket averages, clock-ins, M.O.D. coverage, role groups, POS stock, and group leaderboard every 5 minutes. Kitchen business-date buckets retain 366 days. Employee data every 5 to 15 minutes. Reservations on POS reservation digest ingest.
matriq:read
Covers MatriQ overview, gateway, devices, provider availability, and Auto Scheduler resources.
Gateway and device check-ins on heartbeat. Provider availability on provider artifact upload. Auto Scheduler on publish, draft change, stop, and emergency-stop events.
matriq:ai-scheduler:stop
Allows a location-scoped or group-scoped token to queue an emergency stop for the MatriQ Auto Scheduler.
Immediate action queue. Resulting Auto Scheduler state syncs when the stop event is applied by the gateway.
campaigns:read
Campaign availability, assets, status, and current location or group campaign data.
On demand
orderboard:read
Reserved for current and future OrderBoard Developer API resources.
Coming soon
bevq:read
Reserved for current and future BevQ Developer API resources.
Coming soon
Full response examples live on a dedicated page
The detailed scope and endpoint examples are maintained separately from the main documentation homepage so they can show full response shapes without turning this page into a payload dump.
Full representative payloads for discovery, ShiftQ, SportsQ, MatriQ, Campaigns, OrderBoard, BevQ, and MatriQ Auto Scheduler emergency stop.
/examples
Expanded JSON examples, refresh metadata, token metadata, nested response structures, reservations, leaderboard payloads, and action endpoints.
Module resources
The SmartQ Developer API is organized around discovery endpoints and module-aware location resources.
Locations, location summary, group modules, and location modules.
/locations, /GROUP_ID/modules, /LOCATION_ID/modules
Operational sales, labor, Toast Kitchen ticket averages, POS menu, clock-ins, employee, reservation, and leaderboard data.
/shiftq, /shiftq/sales, /shiftq/labor, /shiftq/kitchen, /shiftq/clock-ins, /shiftq/pos-menu, /shiftq/employees, /shiftq/reservations, /shiftq/toastReservations, /GROUP_ID/shiftq/group-leaderboard
Guide and event schedule payloads, with optional date filtering.
/sportsq
Gateway health, devices, provider availability, Auto Scheduler state, and emergency-stop control.
/matriq, /matriq/gateway, /matriq/devices, /matriq/providerAvailable, /matriq/aiScheduler, POST /matriq/aiScheduler/emergency-stop
Direct alias for provider-ready TV availability, provider logo URLs, and SportsQ event enrichment.
/providerAvailable
Group-level and location-level campaign inventory and status data.
/campaigns
Current placeholder endpoint announcing OrderBoard Developer API availability as work completes.
/orderboard
Current placeholder endpoint announcing BevQ Developer API availability as work completes.
/bevq
SmartQ follows the POS business-day boundary
Sales and ShiftQ business-date resources do not flip at midnight. They follow the location timezone and the
POS business-day rule of 4:01 AM through 4:00 AM.
If the local time is YYYY-MM-DD 3:30 AM, the active business date remains YYYYMMDD.
ShiftQ sales, labor snapshots, Developer API sales resources, and overnight POS fetches that rely on business date.
Every resource declares how fresh it should be
Most responses include a refresh block so downstream developers do not need external documentation to understand cadence.
Typically refreshed every 5 minutes from computed ShiftQ snapshots.
Sales snapshots, compare data, and labor summaries refresh every 5 minutes after POS polling completes. Both endpoints accept ?businessDate=YYYYMMDD, and the API also accepts businessDay=YYYYMMDD. Both use the local 4:01 AM to 4:00 AM business day.
Employee, job, shift, and time-entry collections typically refresh every 5 to 15 minutes.
Stock overlay refreshes every 5 minutes. Scheduled syncs patch changed menus, groups, subgroups, and items into the existing base snapshot. Full base rebuilds are reserved for initial sync or manual forced sync.
Returned from the latest MatriQ provider artifact uploaded for the active business day, such as the guideMatch or /epg/run output.
Published Auto Scheduler state syncs when the draft is published, changed, stopped, or emergency-stopped.
{
"refresh": {
"cadence": "Every 5 minutes",
"description": "Clock-in alerts, role coverage, and attendance exceptions refresh from ShiftQ computed snapshots every 5 minutes."
}
}
Normalized response envelope
All endpoints use a common outer shape so clients can treat resources consistently.
{
"ok": true,
"version": "v1",
"resource": "shiftq/clock-ins",
"groupId": "GROUP_ID",
"locationId": "LOCATION_ID",
"generatedAt": "ISO_TIMESTAMP",
"data": {
"location": {
"id": "LOCATION_ID",
"name": "LOCATION_NAME",
"timezone": "IANA_TIMEZONE"
},
"refresh": {
"cadence": "CADENCE_STRING",
"description": "REFRESH_DESCRIPTION"
}
}
}
Common API responses
- 200 OK: request succeeded.
- 401 Unauthorized: token missing or invalid.
- 403 Forbidden: token revoked, expired, outside allowed locations, or missing the required scope.
- 404 Not Found: group, location, or resource was not found.
- 429 Too Many Requests: token rate limit exceeded.