Vajra Cast REST API: Automate Your Streaming Infrastructure

Why a REST API?

A web UI is great for manual operations: creating a route, checking stream health, adjusting settings during a live event. But modern streaming infrastructure demands automation. You need to spin up routes dynamically, integrate with scheduling systems, trigger failover from external monitors, and manage hundreds of streams without clicking through menus.

Vajra Cast exposes a full REST API that covers every operation available in the web interface. If you can do it in the UI, you can do it with an HTTP request.

API Basics

Base URL

The API is served on the same port as the web interface:

http://your-server:8080/api/v1

All endpoints are prefixed with /api/v1. HTTPS is recommended for production deployments. Put Vajra Cast behind a reverse proxy (Nginx, Caddy, Traefik) with TLS termination.

Authentication

API requests require an API key passed in the Authorization header:

Authorization: Bearer your-api-key-here

API keys are generated in the Vajra Cast web interface under Settings > API Keys. You can create multiple keys with different permissions for different integration points.

Response Format

All responses are JSON. Successful requests return HTTP 200 (or 201 for creation) with the resource data. Errors return appropriate HTTP status codes with a JSON error body:

{
  "error": "not_found",
  "message": "Route with ID 42 does not exist"
}

Core Endpoints

Routes

Routes are the fundamental unit in Vajra Cast. A route connects one or more inputs to one or more outputs, with optional transcoding and failover.

List all routes:

curl -H "Authorization: Bearer $API_KEY" \
  http://localhost:8080/api/v1/routes

Create a route:

curl -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Main Production",
    "enabled": true
  }' \
  http://localhost:8080/api/v1/routes

Get a specific route (with full status):

curl -H "Authorization: Bearer $API_KEY" \
  http://localhost:8080/api/v1/routes/1

Delete a route:

curl -X DELETE -H "Authorization: Bearer $API_KEY" \
  http://localhost:8080/api/v1/routes/1

Inputs

Inputs (ingests) are attached to routes. Each route can have multiple inputs for failover.

Add an SRT listener input to a route:

curl -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "protocol": "srt-listener",
    "port": 9000,
    "latency": 200,
    "passphrase": "MySecurePassphrase2026",
    "pbkeylen": 32,
    "priority": 1
  }' \
  http://localhost:8080/api/v1/routes/1/inputs

Add an RTMP input as a backup:

curl -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "protocol": "rtmp-listener",
    "port": 1935,
    "streamKey": "backup-stream",
    "priority": 2
  }' \
  http://localhost:8080/api/v1/routes/1/inputs

Outputs

Outputs define where the stream goes. Multiple outputs per route are supported (zero-copy distribution).

Add an SRT push output:

curl -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "protocol": "srt-caller",
    "host": "cdn-ingest.example.com",
    "port": 9000,
    "latency": 500,
    "passphrase": "CDNPassphrase2026"
  }' \
  http://localhost:8080/api/v1/routes/1/outputs

Add an RTMP push output (e.g., YouTube Live):

curl -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "protocol": "rtmp-push",
    "url": "rtmp://a.rtmp.youtube.com/live2",
    "streamKey": "your-youtube-stream-key"
  }' \
  http://localhost:8080/api/v1/routes/1/outputs

Status and Metrics

Get real-time status for a route:

curl -H "Authorization: Bearer $API_KEY" \
  http://localhost:8080/api/v1/routes/1/status

Returns the active input, per-input health status, per-output connection status, current bitrate, packet loss, and failover state.

Get system-wide health:

curl http://localhost:8080/api/health

No authentication required. Returns HTTP 200 if the application is running and the database is connected.

Integration Patterns

Scheduled Event Automation

For broadcasters with a schedule (church services, sports events, recurring shows), the API enables full automation:

# 30 minutes before event: create route and inputs
curl -X POST ... /api/v1/routes
curl -X POST ... /api/v1/routes/1/inputs
curl -X POST ... /api/v1/routes/1/outputs

# Event ends: tear down
curl -X DELETE ... /api/v1/routes/1

Integrate this with cron, a scheduling system, or your broadcast automation platform.

Infrastructure as Code

Define your streaming infrastructure in version-controlled scripts. On deployment, the scripts create all routes, inputs, and outputs via the API. If you need to rebuild the system, run the scripts again.

This pairs well with Terraform or Ansible:

# deploy-streams.sh
for route in $(cat routes.json | jq -c '.[]'); do
  curl -X POST -H "Authorization: Bearer $API_KEY" \
    -H "Content-Type: application/json" \
    -d "$route" \
    http://localhost:8080/api/v1/routes
done

External Failover Triggers

Your existing monitoring system (Nagios, Zabbix, Datadog) can trigger failover actions via the API when it detects problems that Vajra Cast’s built-in monitoring might not catch (e.g., content-level issues like wrong camera angle, audio in wrong language):

# Force switch to backup input
curl -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"activeInput": 2}' \
  http://localhost:8080/api/v1/routes/1/failover

Webhook Notifications

Vajra Cast can send webhook notifications for key events (failover switches, connection state changes, errors). Configure webhooks via the API:

curl -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.slack.com/your-webhook",
    "events": ["failover", "disconnect", "reconnect"]
  }' \
  http://localhost:8080/api/v1/webhooks

This enables Slack alerts, PagerDuty integration, or any custom notification workflow.

Rate Limiting and Best Practices

The API does not impose rate limits by default, but follow these best practices:

Poll status endpoints no more than once per second. For real-time metrics, use the Prometheus endpoint instead of polling the REST API.
Use the Prometheus endpoint for monitoring. The /metrics endpoint is designed for high-frequency scraping and is more efficient than the REST status endpoints.
Cache route listings. Route configurations change infrequently. Cache the route list and invalidate on create/delete operations.
Use meaningful route names. Names appear in logs, metrics, and alerts. Main-Production-2026-03-07 is better than route1.

Error Handling

Common error codes and their meanings:

HTTP Code	Meaning	Action
400	Invalid request body	Check JSON structure and required fields
401	Missing or invalid API key	Verify your Authorization header
404	Resource not found	Check the route/input/output ID
409	Conflict (e.g., port already in use)	Choose a different port or remove the conflicting resource
500	Internal server error	Check Vajra Cast logs; report if persistent

Next Steps

Return to the Live Stream Routing Guide for the full routing architecture
Learn about Real-Time Metrics for Prometheus and Grafana monitoring
Explore Docker and Kubernetes Deployment for infrastructure automation

← Back to main guide