SmartQ.tv Developer API Documentation
Customer-facing operational data for venue integrations across ShiftQ, SportsQ, MatriQ, Campaigns, and upcoming OrderBoard resources, plus a narrowly scoped MatriQ AI 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, or OrderBoard 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
Import the official SmartQ.tv workspace files
SmartQ publishes a Postman collection and environment for the full Developer API. Import both files, select the environment,
then paste the bearer token once into the shared token variable.
Includes discovery, ShiftQ, SportsQ, MatriQ, Campaigns, OrderBoard, and legacy compatibility requests.
/postman/SmartQ-Customer-API.postman_collection.json
Shared variables: baseUrl, token, groupId, locationId, and sportsqDate.
/postman/SmartQ-Customer-API.postman_environment.json
- Import both files into Postman.
- Select the SmartQ.tv Developer API environment.
- Enter the API token once in the environment.
- Set
groupIdandlocationIdfor the customer you are testing.
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, clock-ins, POS menu, and employee resources.
Sales, labor, clock-ins, and POS stock every 5 minutes. Employee data every 5 to 15 minutes.
matriq:read
Covers MatriQ overview, gateway, devices, provider availability, and AI Scheduler resources.
Gateway and device check-ins on heartbeat. Provider availability on provider artifact upload. AI 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 AI Scheduler.
Immediate action queue. Resulting AI 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
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, and MatriQ AI Scheduler emergency stop.
/examples.html
Expanded JSON examples, refresh metadata, token metadata, nested strings, and endpoint-specific response structures by scope.
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, POS menu, clock-ins, leaderboard, and labor exception data.
/shiftq · /shiftq/sales · /shiftq/labor · /shiftq/clock-ins · /shiftq/pos-menu · /shiftq/employees
Guide and event schedule payloads, with optional date filtering.
/sportsq
Gateway health, devices, provider availability, AI 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
Older integrations can still use legacy paths while the preferred module structure rolls out.
/sales · /employees · /dtv-available
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 2026-05-17 3:30 AM, the active business date remains 20260516.
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.
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 AI 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": "demo-group",
"locationId": "demo-location",
"generatedAt": "2026-05-17T21:00:00.000Z",
"data": {
"location": {
"id": "demo-location",
"name": "Demo Location",
"timezone": "America/New_York"
},
"refresh": {
"cadence": "Every 5 minutes",
"description": "Clock-in alerts, role coverage, and attendance exceptions refresh from ShiftQ computed snapshots every 5 minutes."
}
}
}
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.