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/sign-upload

Step 1 of direct-upload flow: server generates a Supabase signed upload URL. Browser then PUTs bytes directly to Supabase Storage.

Parameters

namestringrequired— Filename (used to derive extension)
sizenumberrequired— File size in bytes (max 500 MiB)
typestringrequired— MIME type (must start with image/ or video/)
folder_idstring— Optional folder UUID

Response

{ "signedUrl": "...", "token": "...", "path": "<companyId>/<uuid>.<ext>" }
POST/api/media/finalize-upload

Step 3 of direct-upload flow: server HEADs the stored object, validates size + mime, writes the content_blocks row. Orphan is deleted on any failure.

Parameters

pathstringrequired— The path returned by sign-upload
namestringrequired— Display filename
folder_idstring— Optional folder UUID

Response

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

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