v2.4.1 • Stable

API Reference

Welcome to the StarWave Entertainment API. This RESTful API allows developers to programmatically access our catalog of shows, manage live events, query venue availability, and integrate ticketing systems. All endpoints are secured via API keys and support JSON payloads.

Base URL: https://api.starwaveent.com/v2

Content Type: application/json

Authentication

The API uses API keys to authenticate requests. You can view and manage your API keys in the Developer Dashboard. Your API key must be included in the Authorization header of every request.

Authorization: Bearer sk_live_eyJ0eXAiOiJKV1QiLCJhbGc...

Security Warning: Never expose your secret API keys in client-side code or public repositories. Use environment variables to store credentials.

Shows

Manage movies, series, and streaming content.

GET /shows List all shows

Retrieve a paginated list of all available shows. Supports filtering by genre, release year, and status.

Query Parameters

Parameter	Type	Description
`genre`Optional	string	Filter by genre (e.g., `action`, `drama`)
`year`Optional	integer	Filter by release year
`status`Optional	string	Filter by status (`streaming`, `upcoming`)
`limit`Optional	integer	Results per page (default: 20, max: 100)

curl -X GET \"https://api.starwaveent.com/v2/shows?genre=sci-fi&limit=5\" \\
  -H \"Authorization: Bearer $STARWAVE_API_KEY\"

{
  \"data\: [
    {
      \"id\: \"sh_9x82mfk\,
      \"title\: \"Beyond the Horizon\,
      \"genre\: \"sci-fi\,
      \"release_date\: \"2024-03-15\,
      \"status\: \"streaming\
    }
  ],
  \"meta\: {
    \"total\: 142,
    \"page\: 1,
    \"limit\: 5
  }
}

POST /shows Create a new show

Create a new show entry in the catalog. Requires editorial permissions.

Request Body

Parameter	Type	Description
`title`Required	string	Official title of the show
`genre`Required	string	Primary genre category
`description`Optional	string	Synopsis or summary
`release_date`Required	string	ISO 8601 date format

Events

Query and manage live concerts, festivals, and screenings.

GET /events/:id Get event details

Retrieve detailed information about a specific event including venue, schedule, and ticket availability.

// Example Response
{
  \"id\: \"evt_4k29mx\,
  \"name\: \"StarWave Live: Summer Festival\,
  \"venue_id\: \"vn_hollywood_01\,
  \"date\: \"2024-07-20T19:00:00Z\,
  \"status\: \"on_sale\,
  \"capacity\: 15000,
  \"tickets_sold\: 12430
}

Error Codes

StarWave uses conventional HTTP response codes to indicate success or failure. Codes in the 2xx range indicate success, 4xx range indicate client errors, and 5xx range indicate server errors.

Code	Meaning	Description
200	OK	The request succeeded.
201	Created	Resource successfully created.
400	Bad Request	Invalid request body or parameters.
401	Unauthorized	Missing or invalid API key.
403	Forbidden	Insufficient permissions for this resource.
404	Not Found	The requested resource does not exist.
429	Too Many Requests	Rate limit exceeded. Retry after `X-RateLimit-Reset`.
500	Server Error	Internal server error. Please contact support.

Errors are returned in JSON format with a code and message field:

{
  \"error\: {
    \"code\: \"invalid_api_key\,
    \"message\: \"The API key provided is invalid or has been revoked.\,
    \"request_id\: \"req_8f29kx1\
  }
}

Rate Limits

API requests are limited to 1000 requests per minute for standard accounts and 5000 requests per minute for enterprise partners. Rate limit information is returned in response headers:

X-RateLimit-Limit: Maximum requests allowed per window
X-RateLimit-Remaining: Remaining requests in current window
X-RateLimit-Reset: Unix timestamp when the window resets

Pagination

List endpoints return paginated results by default. Use the page and limit query parameters to navigate. The response includes a meta object with pagination details.