WAVE API Documentation

Enterprise-grade APIs for live streaming at 100M+ concurrent user scale

REST API v1

WebSocket API

Production Ready

99.99% SLA

API Base URL

All API requests are made to this base URL

Production Endpoint

https://api.wave.inc/v1

Authentication

Bearer token in Authorization header

Rate Limits

60-1000 req/min based on tier

Response Format

JSON with UTF-8 encoding

API Versioning

We use URL-based versioning (v1, v2, etc.). The current stable version is v1. Major version changes are announced 6 months in advance with migration guides provided.

Getting Started in 4 Steps

From API key to live streaming in under 10 minutes

Get API Key

Generate your API key from the dashboard

Make First Request

Create your first stream via REST API

Connect Real-time

Subscribe to live events with WebSockets

Set Up Webhooks

Receive event notifications in your system

API Documentation Sections

500+ Endpoints

REST API Reference

Complete reference for 500+ REST endpoints covering streams, analytics, content, and more

Learn more

Real-time

WebSocket API

Real-time bidirectional communication for live stream events and analytics updates

Learn more

Event-driven

Webhooks

Configure event-driven integrations with HMAC signature verification

Learn more

6 Languages

Official SDKs

Client libraries for JavaScript, Python, Go, Swift, Kotlin, and Ruby

Learn more

Secure

Authentication

API keys, OAuth 2.0, JWT tokens, and scope-based permission management

Learn more

Scalable

Rate Limits & Quotas

Rate limiting tiers, headers, quotas, and best practices for high-volume usage

Learn more

Example: Create Stream

Complete example with request and response

curl -X POST https://api.wave.inc/v1/streams \
  -H "Authorization: Bearer wave_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Product Launch 2025",
    "protocol": "webrtc",
    "recording": {
      "enabled": true,
      "format": "mp4"
    },
    "transcoding": {
      "enabled": true,
      "profiles": ["720p", "1080p"]
    }
  }'

# Response: 201 Created
{
  "id": "stream_abc123xyz",
  "title": "Product Launch 2025",
  "status": "idle",
  "ingest": {
    "webrtc": {
      "whip_url": "https://rtc.wave.inc/whip/stream_abc123xyz"
    }
  },
  "playback": {
    "hls": "https://stream.wave.inc/hls/stream_abc123xyz/index.m3u8"
  }
}

HTTP Status Codes

Standard status codes used throughout the API

200

OK

Request succeeded

201

Created

Resource created successfully

400

Bad Request

Invalid request parameters

401

Unauthorized

Missing or invalid API key

403

Forbidden

Insufficient permissions

404

Not Found

Resource does not exist

429

Too Many Requests

Rate limit exceeded

500

Internal Server Error

Server error occurred

Common API Patterns

Best practices and patterns for using WAVE API

Error Handling

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": {
      "field": "protocol",
      "reason": "Must be one of: webrtc, rtmp, srt, ndi"
    },
    "request_id": "req_xyz789"
  }
}

Pagination

GET /v1/streams?limit=20&cursor=abc123

{
  "data": [...],
  "pagination": {
    "next_cursor": "def456",
    "has_more": true,
    "total": 150
  }
}

Idempotency

Use the Idempotency-Key header for safe retries on POST/PATCH requests:

POST /v1/streams
Idempotency-Key: unique-uuid-here
Authorization: Bearer wave_live_xxxxx

# Same key within 24h returns same response
# without creating duplicate resources