Overview

This document provides a comprehensive reference for the WINK Streaming Command API, covering WINK Forge, WINK Archive, and WINK Media Router appliances. The API enables programmatic control of video streaming operations, user management, and system administration.

Supported Products

• WINK Forge: Video transcoding and stream management (Firmware 1.6+)
• WINK Archive: Video recording and storage (Firmware 1.1+)
• WINK Media Router: Stream distribution and OTP authentication (Firmware 1.2+)

API Architecture

The WINK API uses XML-based messaging over HTTPS, providing:

• Secure SSL/TLS encrypted communication
• XML request/response format for structured data
• Session-based authentication with optional shared keys
• RESTful design principles for predictable behavior

Getting Started

Authentication

All API calls require authentication using the following XML structure:

<wink_api user='username' pass='password' key='shared_key'>
    <req id='unique_id' command='command_name'>payload</req>
</wink_api>

Authentication Parameters

SSL Requirements

All API endpoints require SSL/HTTPS connections. Configure SSL certificates through:

1. Navigate to Settings → System Options → SSL Certificate
2. Generate self-signed certificate or upload existing certificate
3. For development, use the --insecure flag with cURL to bypass certificate validation

Example Connection

curl -X POST https://10.130.90.188/api/ \
    --insecure \
    --data-urlencode "<wink_api user='apiuser' pass='apipass'>
        <req id='1' command='version'></req>
    </wink_api>" \
    -H 'Content-Type: application/xml'

API Testing Tool

WINK Forge includes a built-in API testing interface:

WINK Forge API Commands

<wink_api user='apiuser' pass='apipass'>
    <req id='1' command='version'></req>
</wink_api>

<wink_api>
    <resp id="1" command="version" status="ok">1.4</resp>
</wink_api>

<wink_api user='apiuser' pass='apipass'>
    <req id='1' command='restart'>WF05-2657-1C04-7F1B-5EC0</req>
</wink_api>

<wink_api>
    <resp id="1" command="restart" status="ok">WF05-2657-1C04-7F1B-5EC0</resp>
</wink_api>

<wink_api user='apiuser' pass='apipass'>
    <req id='1' command='stopip'>10.130.90.68:554</req>
</wink_api>

<wink_api>
    <resp id="1" command="stopip" status="ok">WF05-2657-1C04-7F1B-5EC0</resp>
</wink_api>

GUID Operations

<wink_api user='apiuser' pass='apipass'>
    <req id='1' command='getguid'>10.130.90.199:8382</req>
</wink_api>

<wink_api>
    <resp id="1" command="getguid" status="ok">WF05-2657-1C04-7F1B-5EC0</resp>
</wink_api>

<wink_api user='apiuser' pass='apipass'>
    <req id='1' command='blockguid'>WF05-2657-1C04-7F1B-5EC0</req>
</wink_api>

IP-Based Operations

Stream Management

<wink_api user='apiuser' pass='apipass'>
    <req id='1' command='input_source'>
        <input title='Test Camera' 
               desc='Testing stream' 
               type='RTSP' 
               path='rtsp://192.168.1.100:554/stream1'
               fps='30'
               width='1920'
               height='1080'
               enabled='1' />
    </req>
</wink_api>

User Management

<wink_api user='apiuser' pass='apipass'>
    <req id='1' command='createuser'>
        <name>Billy Armstrong</name>
        <username>billy</username>
        <password>SecurePass123!</password>
        <access>2</access>
    </req>
</wink_api>

System Operations

<wink_api user='apiuser' pass='apipass'>
    <req id='1' command='log'>API integration test successful</req>
</wink_api>

WINK Archive API Commands

Firmware Requirements: Version 1.1 or greater

<wink_api user='apiuser' pass='apipass'>
    <req id='1' command='archiver_start'>WMA5-6E0F-1C04-86F2-E5C4</req>
</wink_api>

<wink_api>
    <resp id="11" command="archiver_status" status="ok">
        <archiver guid="WMA5-6E0F-1C04-86F2-E5C4" 
                  title="TV2" 
                  desc="Conference Room Feed" 
                  type="RTMP" 
                  path="rtmp://10.130.90.10/public/stream_high" 
                  segmenttime="5" 
                  meta1="Building A" 
                  meta2="Floor 2" 
                  meta3="Room 201" 
                  meta4="PTZ Camera" 
                  enabled="1" />
    </resp>
</wink_api>

WINK Media Router API

One-Time Password (OTP) Authentication

The OTP system provides secure, time-limited access to video streams. Key features:

• Server-to-server authentication protocol
• Temporary access tokens for video content
• Configurable expiration times
• Integration with application session management

curl -d "apiuser=apiuser&apipass=apipass&action=create&duration=15&hash_type=numeric&hash_length=20" \
     -X POST http://router.example.com/otp/api/

curl -d "apiuser=apiuser&apipass=apipass&action=extend&token=24814928371014572819&duration=900" \
     -X POST http://router.example.com/api/v1/otp/

Code Examples

JavaScript Integration

Complete JavaScript function for API communication:

function exec_api_command() {
    // Update UI
    document.getElementById("resp_payload").value = "Sending API Command";
    
    // Get connection details
    var api_host = document.getElementById("req_ipaddr").value;
    var payload = document.getElementById("req_payload").value;
    
    // Create request
    var xhttp = new XMLHttpRequest();
    
    // Handle response
    xhttp.onreadystatechange = function() {
        if (xhttp.readyState == 4 && xhttp.status == 200) {
            document.getElementById("resp_payload").value = xhttp.responseText.trim();
        }
    };
    
    // Send request
    xhttp.open("POST", "https://" + api_host.trim() + "/api/", true);
    xhttp.setRequestHeader("Content-type", "application/x-www-form-urlencoded");
    xhttp.send(payload);
}

// Example usage
var xmlPayload = `<wink_api user='apiuser' pass='apipass'>
    <req id='1' command='guidstatus'>WF05-1EDA-1C04-6E33-ABF9</req>
</wink_api>`;

// Call function with payload
document.getElementById("req_payload").value = xmlPayload;
exec_api_command();

Python Integration

import requests
import xml.etree.ElementTree as ET

class WinkAPI:
    def __init__(self, host, username, password, verify_ssl=True):
        self.host = host
        self.username = username
        self.password = password
        self.verify_ssl = verify_ssl
        self.api_url = f"https://{host}/api/"
    
    def execute_command(self, command, payload="", req_id="1"):
        # Build XML request
        xml_request = f"""<wink_api user='{self.username}' pass='{self.password}'>
            <req id='{req_id}' command='{command}'>{payload}</req>
        </wink_api>"""
        
        # Send request
        response = requests.post(
            self.api_url,
            data=xml_request,
            headers={'Content-Type': 'application/xml'},
            verify=self.verify_ssl
        )
        
        # Parse response
        root = ET.fromstring(response.text)
        resp = root.find('resp')
        
        return {
            'status': resp.get('status'),
            'command': resp.get('command'),
            'data': resp.text
        }

# Example usage
api = WinkAPI('10.130.90.188', 'apiuser', 'apipass', verify_ssl=False)

# Get version
version = api.execute_command('version')
print(f"API Version: {version['data']}")

# Check stream status
status = api.execute_command('guidstatus', 'WF05-1EDA-1C04-6E33-ABF9')
print(f"Stream Status: {status['data']}")

cURL Examples

Basic Commands

# Get API version
curl -X POST https://forge.example.com/api/ \
    --insecure \
    --data-urlencode "<wink_api user='apiuser' pass='apipass'><req id='1' command='version'></req></wink_api>" \
    -H 'Content-Type: application/xml'

# Start all streams
curl -X POST https://forge.example.com/api/ \
    --insecure \
    --data-urlencode "<wink_api user='apiuser' pass='apipass'><req id='1' command='start'>all</req></wink_api>" \
    -H 'Content-Type: application/xml'

# Create OTP token
curl -d "apiuser=apiuser&apipass=apipass&action=create&duration=60" \
     -X POST https://router.example.com/otp/api/

Advanced Examples

# Create new input with full configuration
curl -X POST https://forge.example.com/api/ \
    --insecure \
    --data-urlencode "<wink_api user='apiuser' pass='apipass'>
        <req id='1' command='input_source'>
            <input title='Conference Room' 
                   desc='Main conference room HD camera' 
                   type='RTSP' 
                   path='rtsp://admin:password@192.168.1.100:554/stream1'
                   fps='30'
                   width='1920'
                   height='1080'
                   ptz_avail='1'
                   usrlat='41.8781'
                   usrlong='-87.6298'
                   enabled='1' />
        </req>
    </wink_api>" \
    -H 'Content-Type: application/xml'

Notes & Best Practices

API Versioning

• API methods maintain backward compatibility across minor versions
• Major version changes may introduce breaking changes
• Always verify API compatibility before firmware upgrades
• Test API calls on non-production systems first

Performance Considerations

• Batch operations when possible to reduce API calls
• Implement exponential backoff for retry logic
• Monitor API response times for system health
• Use connection pooling for high-frequency operations

Security Best Practices

• Always use HTTPS for API communications
• Implement API-specific user accounts with minimal permissions
• Rotate API credentials regularly
• Log all API access for audit purposes
• Use shared keys for additional security layers

Integration Tips

• OTP expiry should match application session duration
• Implement proper error handling for all API responses
• Cache GUID lookups to reduce API calls
• Use the built-in API testing tool for development

Customer Support

Contact Information

Support Requirements

When contacting support, please provide:

• Customer ID
• System serial number or license key
• Firmware version (from version API command)
• Specific API commands causing issues
• Error messages or unexpected responses
• Network topology if relevant

Additional Resources

• Developer Portal: Access code samples and SDKs
• Community Forum: Share experiences with other developers
• Training Videos: API integration tutorials
• Release Notes: Latest API changes and additions