⏰Event Scheduling

Events API

Schedule & Automate Workflows

Create recurring events, schedule streams, trigger webhooks, and automate tasks with flexible scheduling. Cron expressions, timezone support, and 99.9% reliability.

View Documentation Quickstart Guide

No credit card required

•

14-day free trial

Events API Overview

Complete API for scheduling and managing event-driven automation

Base URL

https://api.wave.online/v1/events

Authentication

Bearer <API_KEY>

Rate Limit

5,000 req/min

What You Can Do

Schedule streams to start/stop at specific times
Create recurring events with cron expressions
Trigger webhooks on schedule or manually
Automate tasks across time zones
Track event execution history and logs

Key Features

Flexible Scheduling - One-time, recurring, or complex cron patterns
Timezone Support - Schedule in any timezone, execute in UTC
Webhook Integration - Trigger custom workflows automatically
Payload Customization - Send custom data to webhooks
99.9% Reliability - Enterprise-grade execution guarantees

API Endpoints

POST/schedules

Create a scheduled event

Request Body

{
  "name": "Daily Stream Kickoff",
  "description": "Starts daily broadcast at 9 AM",
  "type": "stream_start",  // or "webhook", "custom"
  "schedule": {
    "type": "recurring",  // or "one_time"
    "cron": "0 9 * * *",  // 9 AM daily
    "timezone": "America/New_York",
    "startDate": "2024-01-15",
    "endDate": "2024-12-31"
  },
  "action": {
    "streamId": "stream_abc123",
    "action": "start",  // or "stop", "pause", "resume"
    "settings": {
      "quality": "1080p",
      "bitrate": "8000"
    }
  },
  "webhook": {
    "url": "https://yourapp.com/events/stream-started",
    "headers": {
      "Authorization": "Bearer your-token"
    },
    "payload": {
      "eventName": "scheduled_stream_start",
      "customData": {}
    }
  },
  "retryPolicy": {
    "maxRetries": 3,
    "backoffMultiplier": 2,
    "initialDelaySeconds": 5
  },
  "tags": ["daily", "production"]
}

Response (201 Created)

{
  "id": "schedule_abc123",
  "name": "Daily Stream Kickoff",
  "description": "Starts daily broadcast at 9 AM",
  "type": "stream_start",
  "schedule": {
    "type": "recurring",
    "cron": "0 9 * * *",
    "timezone": "America/New_York",
    "nextExecution": "2024-01-15T09:00:00Z",
    "startDate": "2024-01-15",
    "endDate": "2024-12-31"
  },
  "action": { ... },
  "webhook": { ... },
  "retryPolicy": { ... },
  "status": "active",
  "executionCount": 0,
  "lastExecution": null,
  "lastExecutionStatus": null,
  "createdAt": "2024-01-10T14:30:00Z",
  "updatedAt": "2024-01-10T14:30:00Z"
}

Example (cURL)

curl -X POST https://api.wave.online/v1/events/schedules \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Stream Kickoff",
    "type": "stream_start",
    "schedule": {
      "type": "recurring",
      "cron": "0 9 * * *",
      "timezone": "America/New_York"
    },
    "action": {
      "streamId": "stream_abc123",
      "action": "start"
    }
  }'

GET/schedules

List all scheduled events

Query Parameters

limit string - Number of results (default: 50, max: 100)

offset string - Pagination offset (default: 0)

status string - Filter by status: "active", "paused", "completed"

type string - Filter by type: "stream_start", "webhook", "custom"

tag string - Filter by tag name

Response (200 OK)

{
  "data": [
    {
      "id": "schedule_abc123",
      "name": "Daily Stream Kickoff",
      "type": "stream_start",
      "status": "active",
      "nextExecution": "2024-01-15T09:00:00Z",
      "executionCount": 42,
      "lastExecution": "2024-01-14T09:00:15Z",
      "lastExecutionStatus": "success",
      "createdAt": "2024-01-10T14:30:00Z"
    },
    { ... }
  ],
  "pagination": {
    "total": 156,
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}

GET/schedules/:id

Get schedule details by ID

Path Parameters

id string - Schedule ID (e.g., "schedule_abc123")

Response (200 OK)

{
  "id": "schedule_abc123",
  "name": "Daily Stream Kickoff",
  "description": "Starts daily broadcast at 9 AM",
  "type": "stream_start",
  "schedule": {
    "type": "recurring",
    "cron": "0 9 * * *",
    "timezone": "America/New_York",
    "nextExecution": "2024-01-15T09:00:00Z"
  },
  "action": {
    "streamId": "stream_abc123",
    "action": "start",
    "settings": { ... }
  },
  "status": "active",
  "executionCount": 42,
  "lastExecution": "2024-01-14T09:00:15Z",
  "lastExecutionStatus": "success",
  "createdAt": "2024-01-10T14:30:00Z",
  "updatedAt": "2024-01-14T09:00:15Z"
}

PATCH/schedules/:id

Update a scheduled event

Request Body (partial updates)

{
  "name": "Daily Stream Start - Updated",
  "schedule": {
    "cron": "0 10 * * *",  // Changed from 9 AM to 10 AM
    "timezone": "America/Los_Angeles"
  },
  "status": "paused"  // Pause execution
}

Response (200 OK)

Returns updated schedule object

DELETE/schedules/:id

Delete a scheduled event

Response (204 No Content)

Schedule deleted successfully. Future executions will not occur.

POST/schedules/:id/trigger

Manually trigger a scheduled event

Description

Immediately execute a scheduled event, regardless of schedule. Useful for manual triggering or testing.

Response (202 Accepted)

{
  "id": "schedule_abc123",
  "status": "executing",
  "executionId": "exec_xyz789",
  "message": "Event triggered successfully"
}

GET/schedules/:id/executions

Get execution history and logs

Query Parameters

limit string - Number of results (default: 50, max: 100)

status string - Filter: "success", "failed", "skipped"

startDate string - ISO 8601 datetime (e.g., "2024-01-01T00:00:00Z")

endDate string - ISO 8601 datetime

Response (200 OK)

{
  "data": [
    {
      "executionId": "exec_abc123",
      "scheduleId": "schedule_abc123",
      "executedAt": "2024-01-14T09:00:15Z",
      "status": "success",
      "duration": 245,  // milliseconds
      "result": {
        "streamId": "stream_abc123",
        "action": "started",
        "message": "Stream started successfully"
      },
      "webhook": {
        "status": 200,
        "responseTime": 142,
        "payload": { ... }
      },
      "logs": [
        "2024-01-14T09:00:15Z - Preparing stream",
        "2024-01-14T09:00:15Z - Starting broadcast",
        "2024-01-14T09:00:15Z - Webhooks queued"
      ]
    },
    { ... }
  ],
  "pagination": {
    "total": 42,
    "limit": 50,
    "hasMore": false
  }
}

Error Codes

400

Bad Request

Invalid request parameters (e.g., invalid cron expression, missing required fields)

401

Unauthorized

Invalid or missing API key

404

Not Found

Schedule does not exist or has been deleted

409

Conflict

Schedule name already exists or conflict with existing schedule

429

Too Many Requests

Rate limit exceeded (5,000 req/min). Check Retry-After header.

500

Internal Server Error

Server error during event creation or execution. Contact support if persists.

Best Practices

Use Timezone-Aware Scheduling

Always specify timezone in recurring schedules to ensure predictable execution across regions. Use "America/New_York", "Europe/London", etc.

"schedule": {
  "cron": "0 9 * * *",
  "timezone": "America/New_York"
}

Configure Webhooks for Notifications

Set up webhooks to receive notifications on execution. Include retry policies for reliability.

"webhook": {
  "url": "https://yourapp.com/events",
  "retryPolicy": {
    "maxRetries": 3
  }
}

Test Schedules Before Production

Use the /trigger endpoint to test schedules immediately without waiting for next execution.

POST /schedules/schedule_abc123/trigger
# Immediately executes the schedule

Monitor Execution Logs

Use /executions endpoint to monitor schedule health and troubleshoot failures.

GET /schedules/schedule_abc123/executions
  ?status=failed&limit=10
# View recent failures

Code Examples

Schedule a Recurring Stream (JavaScript)

const { WaveClient } = require('@wave/sdk');

const wave = new WaveClient({
  apiKey: process.env.WAVE_API_KEY
});

// Schedule daily stream at 9 AM Eastern
const schedule = await wave.events.createSchedule({
  name: 'Daily Morning Stream',
  type: 'stream_start',
  schedule: {
    type: 'recurring',
    cron: '0 9 * * *',
    timezone: 'America/New_York'
  },
  action: {
    streamId: 'stream_abc123',
    action: 'start',
    settings: {
      quality: '1080p',
      bitrate: '8000'
    }
  },
  webhook: {
    url: 'https://yourapp.com/events',
    payload: {
      eventName: 'stream_started'
    }
  }
});

console.log('Schedule created:', schedule.id);

// Test the schedule
await wave.events.trigger(schedule.id);

// View execution history
const executions = await wave.events.getExecutions(schedule.id);
console.log('Last execution:', executions.data[0]);

Create One-Time Event (Python)

from wave_sdk import WaveClient
from datetime import datetime, timedelta

wave = WaveClient(api_key='sk_live_abc123')

# Schedule stream to start in 1 hour
start_time = datetime.utcnow() + timedelta(hours=1)

schedule = wave.events.create_schedule(
    name='Product Launch Stream',
    type='stream_start',
    schedule={
        'type': 'one_time',
        'executeAt': start_time.isoformat() + 'Z'
    },
    action={
        'streamId': 'stream_abc123',
        'action': 'start'
    },
    webhook={
        'url': 'https://yourapp.com/events',
        'headers': {'Authorization': 'Bearer token'}
    }
)

print(f'Event scheduled: {schedule["id"]}')
print(f'Will execute at: {schedule["schedule"]["executeAt"]}')

Related Resources

Learn more about event scheduling and automation

Event Scheduling Quickstart Webhook Documentation View Full API Docs