API Documentation

REST API reference for the Showcel platform. All endpoints require authentication unless marked as public.

Base URL: https://www.showcel.com/apiAuth: Bearer Token (Supabase JWT)

Screens

GET/api/screens

List all screens for your company.

Response

{ "screens": [{ "id", "name", "status", "resolution", ... }] }
POST/api/screens

Create a new screen.

Parameters

namestringrequired— Screen display name
orientationstring— "landscape" or "portrait"
resolutionstring— e.g. "1920x1080"

Response

{ "screen": { "id", "name", ... } }
GET/api/screens/:id

Get screen details by ID.

PUT/api/screens/:id

Update screen properties.

Parameters

namestring— New name
group_idstring— Assign to group
DELETE/api/screens/:id

Delete a screen permanently.

PUT/api/screens/:id/layout

Update screen canvas layout.

Parameters

layout_configobjectrequired— Canvas layout JSON
POST/api/screens/:id/pair

Generate a 6-digit pair code for device pairing.

Response

{ "pair_code": "ABC123", "expires_at": "..." }
POST/api/screens/:id/apply-template

Apply a template to a screen.

Parameters

templatestringrequired— Template key (e.g. restaurant_menu, welcome_screen)
GET/api/screens/:id/export

Export screen layout as JSON file.

POST/api/screens/:id/import

Import a previously exported layout JSON.

GET/api/screens/health

Get health status for all screens.

Screen Groups

GET/api/screens/groups

List all screen groups.

POST/api/screens/groups

Create a screen group.

Parameters

namestringrequired— Group name
DELETE/api/screens/groups/:id

Delete a screen group.

POST/api/screens/groups/:id/push

Push layout to all screens in a group.

Parameters

layout_configobjectrequired— Layout to push

Content Blocks

GET/api/content-blocks

List all content blocks for your company.

POST/api/content-blocks

Create a content block.

Parameters

namestringrequired— Block name
typestringrequired— image, video, text, widget, web, news
configobject— Block configuration
PUT/api/content-blocks/:id

Update a content block.

DELETE/api/content-blocks/:id

Delete a content block.

POST/api/media/upload

Upload image/video file. Creates content block automatically.

Parameters

fileFilerequired— Image or video file (max 50MB)

Response

{ "success": true, "block": {...}, "url": "..." }

Playlists

GET/api/playlists

List all playlists for your company.

Response

{ "playlists": [{ "id", "name", "is_active", "default_duration", ... }] }
POST/api/playlists

Create a new playlist.

Parameters

namestringrequired— Playlist name
default_durationnumber— Default slide duration in seconds
transitionstring— "fade", "slide", or "none"

Response

{ "playlist": { "id", "name", ... } }
GET/api/playlists/:id

Get playlist with items and schedule data.

PUT/api/playlists/:id

Update playlist settings and/or items.

Parameters

namestring— New name
itemsarray— Array of { block_id, duration } to replace items
transitionstring— Transition type
loopboolean— Loop playback
DELETE/api/playlists/:id

Delete a playlist permanently.

Schedules

GET/api/schedules

List all schedules for your company.

POST/api/schedules

Create a schedule (assigns playlist to screens at specific times).

Parameters

namestringrequired— Schedule name
playlist_idstring— Playlist to schedule
screen_idsarray— Target screen IDs
days_of_weekarray— Days (1=Mon … 7=Sun)
start_timestring— Start time HH:MM
end_timestring— End time HH:MM
PUT/api/content-items/:id/schedule

Set per-item schedule for content within a playlist.

Parameters

scheduleobject|nullrequired— { enabled, days: [0-6], start_time, end_time } or null to clear

Team Management

GET/api/team/members

List team members for your company.

Response

{ "members": [{ "id", "email", "role", "invited_at", ... }] }
POST/api/team/invite

Invite a new team member.

Parameters

emailstringrequired— Invitee email
rolestring— "viewer", "editor", or "admin" (default: viewer)
PUT/api/team/members/:id

Update a team member role.

Parameters

rolestringrequired— New role
DELETE/api/team/members/:id

Remove a team member.

Billing (Stripe)

GET/api/stripe/user-subscription

Get current subscription status and plan details.

POST/api/stripe/checkout

Create a Stripe Checkout session.

Parameters

priceIdstringrequired— Stripe Price ID
planstringrequired— Plan name (pro, enterprise)
POST/api/stripe/portal

Create a Stripe Customer Portal session for self-service billing.

Response

{ "url": "https://billing.stripe.com/..." }
POST/api/stripe/webhookPublic

Stripe webhook handler (internal).

Audit Log

GET/api/audit-log

List audit log entries.

Parameters

actionstring— Filter by action type
limitnumber— Max entries (default: 50)
GET/api/audit-log/export

Export audit log as CSV file.

API Keys

GET/api/api-keys

List your API keys (prefixes only, not full keys).

POST/api/api-keys

Create a new API key.

Parameters

namestringrequired— Key name/description

Response

{ "key": { "id", "name", "key_prefix" }, "full_key": "sc_live_..." }
DELETE/api/api-keys/:id

Revoke an API key.

Other

GET/api/search

Global search across screens, content, playlists.

Parameters

qstringrequired— Search query
GET/api/notifications

List notifications.

PUT/api/notifications/:id

Mark notification as read.

GET/api/support/tickets

List support tickets.

POST/api/support/tickets

Submit a support ticket.

Parameters

subjectstringrequired— Ticket subject
descriptionstringrequired— Issue description
prioritystring— "low", "medium", "high"
GET/api/embed/:idPublic

Embeddable player for iframes.

Analytics

POST/api/analytics/heartbeatPublic

Send a screen heartbeat (used by player).

Parameters

screen_idstringrequired— Screen UUID
GET/api/analytics/dashboard

Get analytics dashboard data.

Parameters

daysnumber— Period in days (default: 7)
GET/api/analytics/export

Export analytics as CSV file.

Parameters

daysnumber— Period in days (default: 7)
GET/api/analytics/screen/:id

Get analytics for a specific screen.

Player (Public)

GET/api/player/:idPublic

Get screen data for the player. No auth required.

Response

{ "screen": { "name", "layout_config", "playlist": { "items": [...] } } }
POST/api/screens/pair/verifyPublic

Verify a pair code and connect device.

Parameters

pair_codestringrequired— 6-character code
device_idstringrequired— Device identifier

Webhooks

GET/api/webhooks

List configured webhooks.

POST/api/webhooks

Create a webhook.

Parameters

urlstringrequired— Webhook endpoint URL
eventsstring[]required— Event types to subscribe to
secretstring— Signing secret for payload verification
DELETE/api/webhooks/:id

Delete a webhook.

Dashboard & User

GET/api/dashboard/stats

Get dashboard summary statistics.

GET/api/dashboard/activity

Get recent activity feed.

GET/api/user/profile

Get current user profile.

PUT/api/user/profile

Update user profile.

Parameters

first_namestring— First name
last_namestring— Last name