Introduction

Welcome to the StarWave Entertainment API documentation. This guide covers everything you need to integrate with our platform — from content management and media processing to live streaming and analytics.

Platform Overview

The StarWave Entertainment API is a comprehensive RESTful API that powers our global entertainment distribution platform. It provides programmatic access to:

Base URL

All API requests are made to the following base URL:

https://api.starwave.io/v3

Response Format

All API responses are returned in JSON format. Successful responses include a data field, while errors include a error object.

{
  "status: "success",
  "data: {
    "id: "cnt_abc123",
    "title: "Beyond the Horizon",
    "type: "film",
    "status: "published",
    "created_at: "2024-01-15T10:30:00Z"
  },
  "meta: {
    "request_id: "req_xyz789",
    "timestamp: "2024-01-15T10:30:05Z"
  }
}

Quick Start

Get up and running with the StarWave API in under 5 minutes. This guide walks you through account setup, authentication, and making your first API call.

Step 1: Create an Account

Sign up at dashboard.starwave.io to create your developer account. Once registered, navigate to Settings → API Keys to generate your credentials.

Step 2: Get Your API Key

You'll need two types of keys:

Step 3: Make Your First Request

Here's how to fetch your first piece of content using cURL:

$ curl -X GET https://api.starwave.io/v3/content \
  -H "Authorization: Bearer SW_TOKEN_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "type": "film",
      "status": "published"
    },
    "limit": 10
  }'

Step 4: Install an SDK

We offer official SDKs for popular languages. Choose your preferred language:

$ npm install @starwave/sdk

const StarWave = require('@starwave/sdk');

const sw = new StarWave({
  apiKey: process.env.STARWAVE_SECRET_KEY,
  version: 'v3'
});

// List all published content
const content = await sw.content.list({
  filter: { status: 'published' },
  limit: 20
});

console.log(`Found ${content.data.length} items`);

$ pip install starwave-sdk

from starwave import Client

sw = Client(api_key=os.getenv("STARWAVE_SECRET_KEY"))

# List all published content
content = sw.content.list(
    filter={"status": "published"},
    limit=20
)

print(f"Found {len(content.data)} items")

$ composer require starwave/sdk

<?php
use StarWave\Client;

$sw = new Client([
    'api_key' => getenv('STARWAVE_SECRET_KEY'),
]);

// List all published content
$content = $sw->content()->list([
    'filter' => ['status' => 'published'],
    'limit' => 20,
]);

echo "Found {count($content->data)} items";

$ go get github.com/starwave/sdk-go/v3

package main

import (
    "fmt"
    "os"
    "github.com/starwave/sdk-go/v3"
)

func main() {
    sw := starwave.New(starwave.Config{
        APIKey: os.Getenv("STARWAVE_SECRET_KEY"),
    })

    content, _ := sw.ListContent(starwave.ContentFilter{
        Status: "published",
        Limit:  20,
    })

    fmt.Printf("Found %d items\n", len(content.Data))
}

Authentication

StarWave API uses multiple authentication methods depending on the operation type. All API requests require authentication except for public content discovery endpoints.

Authentication Methods

"Authorization": "Bearer SW_SEC_xxxxx"

"Authorization": "Bearer eyJhbG..."

"Authorization": "Bearer oauth_token"

Obtaining a JWT Token

Exchange your API key for a short-lived JWT token:

{
  "grant_type": "api_key",
  "api_key": "SW_SEC_your_secret_key",
  "expires_in": 3600
}

{
  "status": "success",
  "data": {
    "access_token": "eyJhbGciOiJSUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "read write"
  }
}

Rate Limits

To ensure fair usage and platform stability, API requests are rate-limited based on your account tier. All rate limit information is included in response headers.

Rate Limit Tiers

Response Headers

Every API response includes rate limit information in the headers:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 298
X-RateLimit-Reset: 1705312200
X-RateLimit-Burst-Limit: 50
X-RateLimit-Burst-Remaining: 48

List Content

Retrieve a paginated list of content items with optional filtering, sorting, and field selection.

$ curl -X GET "https://api.starwave.io/v3/content?type=film&status=published&limit=10&sort=created_at" \
  -H "Authorization: Bearer SW_TOKEN_abc123"

{
  "status": "success",
  "data": [
    {
      "id": "cnt_abc123",
      "title": "Beyond the Horizon",
      "type": "film",
      "status": "published",
      "genre": ["sci-fi", "drama"],
      "duration": 7320,
      "views": 2450000,
      "thumbnail": "https://cdn.starwave.io/thumbs/cnt_abc123.jpg",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-16T08:00:00Z"
    }
  ],
  "pagination": {
    "total": 142,
    "limit": 10,
    "offset": 0,
    "has_more": true,
    "next_cursor": "eyJpZCI6ImNudF94eXo3ODkifQ"
  }
}

Create Content

Create a new content item in the system. After creation, upload media files using the returned upload URL.

const response = await sw.content.create({
  title: "Thunder Strike",
  type: "film",
  description: "An action-packed thriller set in the heart of the storm...",
  genre: ["action", "thriller"],
  language: "en",
  drm_enabled: true,
  metadata: {
    director: "James Chen",
    studio: "StarWave Studios",
    budget_tier: "blockbuster"
  }
});

console.log(`Created: ${response.data.id}`);
console.log(`Upload URL: ${response.data.upload_url}`);

Upload Media

Upload video, audio, and image assets to the StarWave media processing pipeline. Files are automatically transcoded into multiple formats for optimal playback.

// Step 1: Request presigned URL
const upload = await sw.media.requestUpload({
  content_id: "cnt_abc123",
  filename: "movie_final.mp4",
  content_type: "video/mp4",
  file_size: 4294967296, // 4GB
  method: "presigned"
});

// Step 2: Upload directly to the URL
await fetch(upload.presigned_url, {
  method: "PUT",
  body: fileBuffer,
  headers: {
    "Content-Type": "video/mp4"
  }
});

// Step 3: Confirm upload
const result = await sw.media.confirmUpload(upload.upload_id);
console.log(`Processing started: ${result.status}`);

Webhooks

Receive real-time notifications when events occur in your StarWave account. Configure webhook endpoints through the dashboard or API.

Event Types

Webhook Payload Structure

{
  "id": "evt_abc123",
  "type": "media.transcoded",
  "timestamp": "2024-01-15T14:22:00Z",
  "data": {
    "media_id": "med_xyz789",
    "content_id": "cnt_abc123",
    "formats": [
      { "quality": "1080p", "bitrate": 5000000, "url": "..." },
      { "quality": "720p",  "bitrate": 2500000, "url": "..." },
      { "quality": "480p",  "bitrate": 1000000, "url": "..." }
    ],
    "duration": 7320,
    "size_bytes": 107374182400
  }
}

Signature Verification

Every webhook includes a X-Webhook-Signature header. Verify it using your webhook secret:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Changelog

Track changes to the StarWave API. We follow semantic versioning and maintain backward compatibility within major versions.

Error Reference

All error responses follow a consistent format. The error object includes a machine-readable code and a human-readable message.

{
  "status": "error",
  "error": {
    "code": "CONTENT_NOT_FOUND",
    "message": "No content found with ID 'cnt_invalid'",
    "type": "not_found",
    "details": {
      "content_id": "cnt_invalid"
    },
    "request_id": "req_xyz789"
  }
}

Common Error Codes