Developer API Examples

String-Format Response Examples

These are structure examples only. They intentionally use placeholder values such as GROUP_ID, LOCATION_ID, ISO_TIMESTAMP, STATUS_STRING, and NUMBER instead of venue-specific data.

locations:read

Discovery Example

{
  "ok": true,
  "version": "v1",
  "resource": "locations",
  "groupId": "GROUP_ID",
  "generatedAt": "ISO_TIMESTAMP",
  "token": {
    "scopeType": "group_or_location",
    "scopes": ["locations:read", "shiftq:read", "matriq:read"],
    "rateLimitPerMinute": "NUMBER",
    "expiresAt": "ISO_TIMESTAMP_OR_NULL",
    "status": "active_or_revoked_or_expired",
    "allowedLocationIds": ["LOCATION_ID_IF_LOCATION_SCOPED"],
    "tokenPrefix": "TOKEN_PREFIX"
  },
  "data": {
    "refresh": {
      "cadence": "CADENCE_STRING",
      "description": "REFRESH_DESCRIPTION"
    },
    "locations": [
      {
        "id": "LOCATION_ID",
        "name": "LOCATION_NAME",
        "locationShortName": "LOCATION_SHORT_NAME",
        "timezone": "IANA_TIMEZONE",
        "slug": "LOCATION_SLUG",
        "status": "STATUS_STRING",
        "modulesEnabled": {
          "shiftq": "BOOLEAN",
          "sportsq": "BOOLEAN",
          "matriq": "BOOLEAN",
          "campaigns": "BOOLEAN",
          "orderboard": "BOOLEAN"
        },
        "resources": ["RESOURCE_NAME"],
        "endpoints": {
          "root": "https://api.smartq.tv/v1/GROUP_ID/LOCATION_ID",
          "modules": "https://api.smartq.tv/v1/GROUP_ID/LOCATION_ID/modules",
          "shiftq": "https://api.smartq.tv/v1/GROUP_ID/LOCATION_ID/shiftq",
          "sportsq": "https://api.smartq.tv/v1/GROUP_ID/LOCATION_ID/sportsq",
          "matriq": "https://api.smartq.tv/v1/GROUP_ID/LOCATION_ID/matriq"
        }
      }
    ]
  }
}

shiftq:read

ShiftQ Overview Example

{
  "ok": true,
  "version": "v1",
  "resource": "shiftq",
  "groupId": "GROUP_ID",
  "locationId": "LOCATION_ID",
  "generatedAt": "ISO_TIMESTAMP",
  "data": {
    "location": {
      "id": "LOCATION_ID",
      "name": "LOCATION_NAME",
      "timezone": "IANA_TIMEZONE"
    },
    "refresh": {
      "sales": { "cadence": "CADENCE_STRING", "description": "SALES_REFRESH_DESCRIPTION" },
      "labor": { "cadence": "CADENCE_STRING", "description": "LABOR_REFRESH_DESCRIPTION" },
      "posMenu": { "cadence": "CADENCE_STRING", "description": "POS_MENU_REFRESH_DESCRIPTION" },
      "clockIns": { "cadence": "CADENCE_STRING", "description": "CLOCK_IN_REFRESH_DESCRIPTION" },
      "employees": { "cadence": "CADENCE_STRING", "description": "EMPLOYEE_REFRESH_DESCRIPTION" }
    },
    "summary": {
      "businessDate": "YYYYMMDD",
      "salesUpdatedAt": "ISO_TIMESTAMP",
      "laborUpdatedAt": "ISO_TIMESTAMP",
      "top5Leaderboard": [
        { "employeeId": "EMPLOYEE_ID", "employeeName": "EMPLOYEE_NAME", "metric": "METRIC_NAME", "value": "NUMBER", "rank": "NUMBER" }
      ],
      "clockedInCount": "NUMBER",
      "soldOutItemCount": "NUMBER"
    }
  }
}

shiftq:read

ShiftQ POS Menu Example

{
  "ok": true,
  "version": "v1",
  "resource": "shiftq/pos-menu",
  "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": "POS_MENU_REFRESH_DESCRIPTION"
    },
    "syncStatus": {
      "lastStatus": "STATUS_STRING",
      "lastCheckedAt": "ISO_TIMESTAMP",
      "lastSyncedAt": "ISO_TIMESTAMP",
      "fullMenuRewrite": "POLICY_STRING",
      "incrementalBaseUpdates": "POLICY_STRING",
      "stockOverlayRefresh": "CADENCE_STRING"
    },
    "menuMetadata": {
      "restaurantGuid": "POS_RESTAURANT_GUID",
      "lastUpdated": "ISO_TIMESTAMP"
    },
    "menuSnapshot": {
      "lastUpdated": "ISO_TIMESTAMP",
      "lastSynced": "ISO_TIMESTAMP"
    },
    "soldOutItems": {
      "count": "NUMBER",
      "items": [
        { "key": "LOCATION_ID:INDEX:ITEM_NAME", "name": "ITEM_NAME" }
      ]
    }
  }
}

sportsq:read

SportsQ Example

{
  "ok": true,
  "version": "v1",
  "resource": "sportsq",
  "groupId": "GROUP_ID",
  "locationId": "LOCATION_ID",
  "generatedAt": "ISO_TIMESTAMP",
  "data": {
    "location": {
      "id": "LOCATION_ID",
      "name": "LOCATION_NAME",
      "timezone": "IANA_TIMEZONE"
    },
    "effectiveDate": "YYYY-MM-DD",
    "refresh": {
      "cadence": "CADENCE_STRING"
    },
    "guide": [
      {
        "eventId": "EVENT_ID",
        "title": "EVENT_TITLE",
        "league": "LEAGUE_NAME",
        "homeTeam": "HOME_TEAM_NAME",
        "awayTeam": "AWAY_TEAM_NAME"
      }
    ]
  }
}

matriq:read

MatriQ Overview Example

{
  "ok": true,
  "version": "v1",
  "resource": "matriq",
  "groupId": "GROUP_ID",
  "locationId": "LOCATION_ID",
  "generatedAt": "ISO_TIMESTAMP",
  "data": {
    "location": {
      "id": "LOCATION_ID",
      "name": "LOCATION_NAME",
      "timezone": "IANA_TIMEZONE"
    },
    "refresh": {
      "gateway": { "cadence": "CADENCE_STRING" },
      "devices": { "cadence": "CADENCE_STRING" },
      "providerAvailable": { "cadence": "CADENCE_STRING", "description": "PROVIDER_REFRESH_DESCRIPTION" },
      "aiScheduler": { "cadence": "CADENCE_STRING", "description": "AI_SCHEDULER_REFRESH_DESCRIPTION" }
    },
    "summary": {
      "deviceIds": ["DEVICE_ID"],
      "providerCount": "NUMBER",
      "artifactCount": "NUMBER",
      "latestProviderArtifactUpdatedAt": "ISO_TIMESTAMP",
      "aiSchedulerPublished": "BOOLEAN",
      "aiSchedulerRunning": "BOOLEAN"
    }
  }
}

matriq:read

Provider Availability Example

{
  "ok": true,
  "version": "v1",
  "resource": "providerAvailable",
  "groupId": "GROUP_ID",
  "locationId": "LOCATION_ID",
  "generatedAt": "ISO_TIMESTAMP",
  "data": {
    "location": {
      "id": "LOCATION_ID",
      "name": "LOCATION_NAME",
      "timezone": "IANA_TIMEZONE"
    },
    "deviceIds": ["DEVICE_ID"],
    "businessDate": {
      "active": "YYYYMMDD",
      "calendarDate": "YYYY-MM-DD",
      "timezone": "IANA_TIMEZONE"
    },
    "providers": [
      {
        "providerKey": "PROVIDER_KEY",
        "providerLabel": "PROVIDER_LABEL",
        "providerLogo": "PROVIDER_LOGO_URL"
      }
    ],
    "artifacts": [
      {
        "source": "ARTIFACT_SOURCE",
        "deviceId": "DEVICE_ID",
        "path": "BUCKET_PATH/provider-available-YYYY-MM-DD.json",
        "updatedAt": "ISO_TIMESTAMP"
      }
    ],
    "providersAvailable": [
      {
        "eventId": "EVENT_ID",
        "title": "EVENT_TITLE",
        "league": "LEAGUE_NAME",
        "leagueLogo": "LEAGUE_LOGO_URL",
        "homeTeam": "HOME_TEAM_NAME",
        "awayTeam": "AWAY_TEAM_NAME",
        "homeLogo": "HOME_TEAM_LOGO_URL",
        "awayLogo": "AWAY_TEAM_LOGO_URL",
        "providerLabel": "PROVIDER_LABEL",
        "providerLogo": "PROVIDER_LOGO_URL",
        "channelNumber": "CHANNEL_NUMBER"
      }
    ]
  }
}

matriq:read

AI Scheduler Example

{
  "ok": true,
  "version": "v1",
  "resource": "matriq/aiScheduler",
  "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": "AI_SCHEDULER_REFRESH_DESCRIPTION"
    },
    "deviceIds": ["DEVICE_ID"],
    "businessDay": "YYYYMMDD",
    "statusUpdatedAt": "ISO_TIMESTAMP",
    "publishedDraftUpdatedAt": "ISO_TIMESTAMP",
    "status": {
      "running": "BOOLEAN",
      "published": "BOOLEAN",
      "draftExists": "BOOLEAN",
      "runtime": {
        "emergencyStopActive": "BOOLEAN",
        "lastStartAt": "ISO_TIMESTAMP_OR_NULL",
        "lastStopAt": "ISO_TIMESTAMP_OR_NULL"
      }
    },
    "currentPublishedDraft": {
      "businessDay": "YYYYMMDD",
      "published": "BOOLEAN",
      "status": "STATUS_STRING",
      "draft": {
        "title": "DRAFT_TITLE",
        "items": [
          { "id": "SCHEDULE_ITEM_ID", "start": "HH:MM", "end": "HH:MM", "eventTitle": "EVENT_TITLE" }
        ]
      }
    },
    "actions": [
      {
        "label": "Emergency Stop AI Scheduler",
        "method": "POST",
        "endpoint": "https://api.smartq.tv/v1/GROUP_ID/LOCATION_ID/matriq/aiScheduler/emergency-stop",
        "scope": "matriq:ai-scheduler:stop",
        "description": "ACTION_DESCRIPTION"
      }
    ]
  }
}

matriq:ai-scheduler:stop

Emergency Stop Example

{
  "ok": true,
  "version": "v1",
  "resource": "matriq/aiScheduler/emergency-stop",
  "groupId": "GROUP_ID",
  "locationId": "LOCATION_ID",
  "generatedAt": "ISO_TIMESTAMP",
  "data": {
    "status": "queued_or_applied_or_failed",
    "deviceId": "DEVICE_ID",
    "commandId": "COMMAND_ID",
    "requestedAt": "ISO_TIMESTAMP",
    "reason": "REASON_STRING",
    "refresh": {
      "cadence": "CADENCE_STRING",
      "description": "AI_SCHEDULER_REFRESH_DESCRIPTION"
    }
  }
}

campaigns:read

Campaigns Example

{
  "ok": true,
  "version": "v1",
  "resource": "campaigns",
  "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": "CAMPAIGN_REFRESH_DESCRIPTION"
    },
    "campaigns": [
      {
        "id": "CAMPAIGN_ID",
        "name": "CAMPAIGN_NAME",
        "status": "STATUS_STRING",
        "startsAt": "ISO_TIMESTAMP",
        "endsAt": "ISO_TIMESTAMP"
      }
    ],
    "deviceStatus": {
      "healthy": "NUMBER",
      "warning": "NUMBER",
      "offline": "NUMBER"
    }
  }
}

orderboard:read

OrderBoard Example

{
  "ok": true,
  "version": "v1",
  "resource": "orderboard",
  "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": "ORDERBOARD_REFRESH_DESCRIPTION"
    },
    "status": "coming_soon",
    "message": "ORDERBOARD_STATUS_MESSAGE"
  }
}