API Authentication and Examples
API integrations should authenticate, confirm system health, discover current IDs, and then send deliberate control commands with predictable payloads and error handling.
Screenshot is coming soon...
What you will learn
- How to structure API calls safely.
- How to use discovery endpoints before control endpoints.
- How to design live-safe external panels.
Recommended workflow
- Store the API token securely in the calling system.
- Send the token in the authorization header required by the docs API/server configuration.
- Call GET /api/status before live commands.
- Call list endpoints to resolve current inputs, functions, scenes, or videos.
- Send POST commands only after confirming the target exists.
- Log request, response, timestamp, and operator identity when possible.
Buttons, fields, and controls
| Control | What it does | When to use it |
|---|---|---|
| Authorization header | Carries the API token. | Use for every protected API request. |
| GET before POST | Discovers current state before changing state. | Use to reduce wrong-target mistakes. |
| Status check | Confirms server readiness. | Use before opening external control surfaces. |
| Idempotent panel design | Prevents repeated clicks from causing unexpected output. | Use for custom buttons and automation. |
| Error display | Shows API errors to operators. | Use so failures are visible immediately. |
Best practices
- Never hard-code show-specific IDs without a discovery step.
- Use confirmation for Program, Clear, Fade-to-Black, and other destructive/live actions.
- Rate-limit external automation buttons to prevent accidental double triggers.
Troubleshooting
| Symptom | Likely cause | What to check |
|---|---|---|
| 401/403 response | Missing or invalid token. | Check authorization header and token value. |
| 404 response | Endpoint or target ID does not exist. | Refresh API docs and discovery lists. |
| 500 response | Server-side or subsystem error. | Check Monitor and server logs. |
Screenshot is coming soon...