API Getting Started

API Keys

The SimplyStream API uses API keys for authentication. Every account has a unique API key (a UUID) that is assigned when you sign up. All API requests must include this key in the Authorization header as a Bearer token.

Finding Your API Key

Your API key is shown under API Key on your Profile page. Hover to reveal it, or click the copy button. You can also find it in the interactive API docs, which let you test endpoints directly from the browser.

Using Your API Key

Include your API key in all API requests using the Authorization header:

curl https://api.simplystream.com/api/v1/projects \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('https://api.simplystream.com/api/v1/projects', {
	headers: {
		Authorization: `Bearer ${process.env.SIMPLYSTREAM_API_KEY}`,
		'Content-Type': 'application/json'
	}
});

const data = await response.json();
console.log(data.result);

import requests
import os

response = requests.get(
    'https://api.simplystream.com/api/v1/projects',
    headers={
        'Authorization': f'Bearer {os.getenv("SIMPLYSTREAM_API_KEY")}',
        'Content-Type': 'application/json'
    }
)

data = response.json()
print(data['result'])

Best Practices

Security:

• Never commit API keys to version control
• Use environment variables to store keys
• Restrict API key access to trusted services

Environment Variables:

# .env file (add to .gitignore!)
SIMPLYSTREAM_API_KEY=your-uuid-api-key-here

// Node.js
require('dotenv').config();
const apiKey = process.env.SIMPLYSTREAM_API_KEY;

# Python
from dotenv import load_dotenv
import os

load_dotenv()
api_key = os.getenv('SIMPLYSTREAM_API_KEY')

List Projects

Get all your projects:

curl https://api.simplystream.com/api/v1/projects \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('https://api.simplystream.com/api/v1/projects', {
	headers: {
		Authorization: `Bearer ${process.env.SIMPLYSTREAM_API_KEY}`
	}
});

const { result } = await response.json();
console.log(result); // Array of projects

import requests
import os

response = requests.get(
    'https://api.simplystream.com/api/v1/projects',
    headers={'Authorization': f'Bearer {os.getenv("SIMPLYSTREAM_API_KEY")}'}
)

projects = response.json()['result']
print(projects)

Create a Project

curl -X POST https://api.simplystream.com/api/v1/projects \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My New Project"}'

const response = await fetch('https://api.simplystream.com/api/v1/projects', {
	method: 'POST',
	headers: {
		Authorization: `Bearer ${process.env.SIMPLYSTREAM_API_KEY}`,
		'Content-Type': 'application/json'
	},
	body: JSON.stringify({ name: 'My New Project' })
});

const { project_id } = await response.json();
console.log(`Created project: ${project_id}`);

import requests
import os

response = requests.post(
    'https://api.simplystream.com/api/v1/projects',
    headers={
        'Authorization': f'Bearer {os.getenv("SIMPLYSTREAM_API_KEY")}',
        'Content-Type': 'application/json'
    },
    json={'name': 'My New Project'}
)

data = response.json()
print(f'Created project: {data["project_id"]}')

Start a Streaming Session

Allocate a server and start a streaming session for a project:

curl -X POST https://api.simplystream.com/api/v1/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project_id": "your-project-id"}'

const response = await fetch('https://api.simplystream.com/api/v1/sessions', {
	method: 'POST',
	headers: {
		Authorization: `Bearer ${process.env.SIMPLYSTREAM_API_KEY}`,
		'Content-Type': 'application/json'
	},
	body: JSON.stringify({ project_id: projectId })
});

const session = await response.json();
console.log(`Session started: ${session.result}`);

Manage Nameservers

Nameservers provide whitelabel DNS routing for streaming sessions.

List Nameservers

curl https://api.simplystream.com/api/v1/nameservers \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('https://api.simplystream.com/api/v1/nameservers', {
	headers: {
		Authorization: `Bearer ${process.env.SIMPLYSTREAM_API_KEY}`
	}
});

const { results } = await response.json();
console.log(results);

Create Nameserver

curl -X POST https://api.simplystream.com/api/v1/nameservers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "route": "streaming.yourcompany.com",
    "name": "Production Nameserver"
  }'

const response = await fetch('https://api.simplystream.com/api/v1/nameservers', {
	method: 'POST',
	headers: {
		Authorization: `Bearer ${process.env.SIMPLYSTREAM_API_KEY}`,
		'Content-Type': 'application/json'
	},
	body: JSON.stringify({
		route: 'streaming.yourcompany.com',
		name: 'Production Nameserver'
	})
});

const nameserver = await response.json();
console.log(`Created nameserver: ${nameserver.result}`);

Set Project Nameserver

curl -X PUT https://api.simplystream.com/api/v1/projects/{project_id}/nameserver \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"nameserverId": "your-nameserver-id"}'

await fetch(`https://api.simplystream.com/api/v1/projects/${projectId}/nameserver`, {
	method: 'PUT',
	headers: {
		Authorization: `Bearer ${process.env.SIMPLYSTREAM_API_KEY}`,
		'Content-Type': 'application/json'
	},
	body: JSON.stringify({ nameserverId: 'your-nameserver-id' })
});

// Clear project nameserver (use default)
await fetch(`https://api.simplystream.com/api/v1/projects/${projectId}/nameserver`, {
	method: 'PUT',
	headers: {
		Authorization: `Bearer ${process.env.SIMPLYSTREAM_API_KEY}`,
		'Content-Type': 'application/json'
	},
	body: JSON.stringify({ nameserverId: null })
});

Set Endpoint Nameserver Override

Override the project's default nameserver for a specific endpoint:

curl -X PUT https://api.simplystream.com/api/v1/endpoints/{endpoint_id}/nameserver \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"nameserverId": "your-nameserver-id"}'

List Endpoints

Get endpoints for a project:

curl "https://api.simplystream.com/api/v1/endpoints?project_id={project_id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
	`https://api.simplystream.com/api/v1/endpoints?project_id=${projectId}`,
	{
		headers: {
			Authorization: `Bearer ${process.env.SIMPLYSTREAM_API_KEY}`
		}
	}
);

const { results } = await response.json();
console.log(results);

Get Analytics

Concurrent Users

curl "https://api.simplystream.com/api/v1/analytics/concurrent-users?time_window_hours=24" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
	'https://api.simplystream.com/api/v1/analytics/concurrent-users?time_window_hours=24',
	{
		headers: {
			Authorization: `Bearer ${process.env.SIMPLYSTREAM_API_KEY}`
		}
	}
);

const { results } = await response.json();
console.log(results); // [{ timestamp, users }, ...]

Quality Stats

curl "https://api.simplystream.com/api/v1/analytics/quality-stats" \
  -H "Authorization: Bearer YOUR_API_KEY"

CI/CD Integration

Automate deployments from your CI/CD pipeline. This example uses the SimplyStream CLI to upload a new build revision:

# GitHub Actions example
name: Deploy to SimplyStream

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build application
        run: |
          npm install
          npm run build
          zip -r build.zip dist/

      - name: Deploy to SimplyStream
        env:
          SIMPLYSTREAM_API_KEY: ${{ secrets.SIMPLYSTREAM_API_KEY }}
          PROJECT_ID: ${{ secrets.SIMPLYSTREAM_PROJECT_ID }}
        run: |
          npx simplystreamcli upload \
            --project $PROJECT_ID \
            --file build.zip \
            --api-key $SIMPLYSTREAM_API_KEY

You can also use the API directly to manage projects from CI:

async function ensureProjectExists(name) {
	const headers = {
		Authorization: `Bearer ${process.env.SIMPLYSTREAM_API_KEY}`,
		'Content-Type': 'application/json'
	};

	// Check if project already exists
	const listResponse = await fetch('https://api.simplystream.com/api/v1/projects', { headers });

	const { result: projects } = await listResponse.json();
	const existing = projects.find((p) => p.name === name);
	if (existing) return existing.id;

	// Create if not found
	const createResponse = await fetch('https://api.simplystream.com/api/v1/projects', {
		method: 'POST',
		headers,
		body: JSON.stringify({ name })
	});

	const { project_id } = await createResponse.json();
	return project_id;
}

Monitoring Active Sessions

Monitor your active streaming sessions and send alerts:

async function monitorSessions() {
	const response = await fetch('https://api.simplystream.com/api/v1/sessions', {
		headers: {
			Authorization: `Bearer ${process.env.SIMPLYSTREAM_API_KEY}`
		}
	});

	const { results } = await response.json();
	const activeSessions = results.filter((s) => s.status === 'running');

	console.log(`Active sessions: ${activeSessions.length}`);

	// Alert on high concurrent usage
	if (activeSessions.length > 50) {
		sendAlert(`High session count: ${activeSessions.length} active sessions`);
	}

	return activeSessions;
}

Usage Analytics

Track concurrent users over time to understand demand patterns:

import requests
import os

def get_concurrent_users(hours=24):
    """Get concurrent user counts for the last N hours"""
    response = requests.get(
        'https://api.simplystream.com/api/v1/analytics/concurrent-users',
        headers={'Authorization': f'Bearer {os.getenv("SIMPLYSTREAM_API_KEY")}'},
        params={'time_window_hours': hours}
    )

    data = response.json()
    results = data['results']

    peak = max(results, key=lambda r: r['users'])
    print(f'Peak concurrent users: {peak["users"]} at {peak["timestamp"]}')

    return results

get_concurrent_users(24)

Quality Monitoring

Detect problematic sessions and quality issues:

async function checkQuality() {
	const headers = {
		Authorization: `Bearer ${process.env.SIMPLYSTREAM_API_KEY}`
	};

	// Get quality stats
	const statsResponse = await fetch('https://api.simplystream.com/api/v1/analytics/quality-stats', {
		headers
	});
	const stats = await statsResponse.json();

	// Get problematic sessions
	const problemResponse = await fetch('https://api.simplystream.com/api/v1/analytics/problematic', {
		headers
	});
	const problems = await problemResponse.json();

	if (problems.results?.length > 0) {
		console.warn(`${problems.results.length} problematic sessions detected`);
	}

	return { stats, problems };
}

Server Profile Management

Create and manage server profiles for different use cases:

async function createServerProfile(name, config) {
	const response = await fetch('https://api.simplystream.com/api/v1/server_profiles', {
		method: 'POST',
		headers: {
			Authorization: `Bearer ${process.env.SIMPLYSTREAM_API_KEY}`,
			'Content-Type': 'application/json'
		},
		body: JSON.stringify({ name, ...config })
	});

	return response.json();
}

// Estimate costs before creating
async function estimateCost(config) {
	const response = await fetch(
		'https://api.simplystream.com/api/v1/server_profiles/estimate-cost',
		{
			method: 'POST',
			headers: {
				Authorization: `Bearer ${process.env.SIMPLYSTREAM_API_KEY}`,
				'Content-Type': 'application/json'
			},
			body: JSON.stringify(config)
		}
	);

	const estimate = await response.json();
	console.log(`Estimated cost: $${estimate.result?.cost_per_hour}/hr`);
	return estimate;
}

Base URL

All API requests should be made to:

https://api.simplystream.com/api/v1

Authentication

All requests require a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Response Format

All responses are JSON. Most endpoints use the following structure:

Success (list):

{
  "success": true,
  "results": [...]
}

Success (single resource):

{
  "success": true,
  "result": { ... }
}

Success (creation):

{
	"success": true,
	"project_id": "uuid"
}

Error Response:

{
	"success": false,
	"msg": "Error description"
}

HTTP Status Codes

• 200 OK - Request succeeded
• 201 Created - Resource created
• 400 Bad Request - Invalid request parameters
• 401 Unauthorized - Invalid or missing API key
• 403 Forbidden - Insufficient permissions
• 404 Not Found - Resource not found
• 500 Internal Server Error - Server error

Core Endpoints

Projects

Method	Path	Description
GET	/projects	List all projects
POST	/projects	Create a project (body: { name })
GET	/projects/{id}	Get project details
PATCH	/projects/{id}	Update project
DELETE	/projects/{id}	Delete project
GET	/projects/{id}/members	List project members

Sessions

Method	Path	Description
GET	/sessions	List sessions
POST	/sessions	Allocate a streaming session
GET	/sessions/{id}	Get session details
GET	/sessions/{id}/allocation	Check allocation status
DELETE	/sessions/{id}	Terminate a session
GET	/sessions/{id}/log	Get session log
GET	/sessions/{id}/metrics	Get session metrics
POST	/sessions/quick-start	Quick-start a session

Revisions

Method	Path	Description
GET	/projects/{id}/revisions	List revisions for a project
GET	/projects/{id}/revisions/active	Get active revision
PUT	/projects/{id}/revisions/active	Set active revision
PATCH	/projects/{id}/revisions/{rev}	Update a revision
DELETE	/projects/{id}/revisions/{rev}	Delete a revision

Uploading builds: Use the SimplyStream CLI (simplystreamcli upload) to upload new revisions. The CLI handles binary asset packaging and upload automatically.

Endpoints

Method	Path	Description
GET	/endpoints	List endpoints (use ?project_id= to filter)
POST	/endpoints	Create/update endpoint
DELETE	/endpoints/{id}	Delete endpoint
PUT	/endpoints/{id}/fast-mode	Toggle fast mode
PUT	/endpoints/{id}/nameserver	Set endpoint nameserver override

Nameservers

Method	Path	Description
GET	/nameservers	List your nameservers
POST	/nameservers	Create a nameserver
PUT	/nameservers/{id}	Update a nameserver
DELETE	/nameservers/{id}	Delete a nameserver
POST	/nameservers/{id}/verify	Verify nameserver DNS
GET	/projects/{id}/nameserver	Get project nameserver
PUT	/projects/{id}/nameserver	Set project nameserver

Server Profiles

Method	Path	Description
GET	/server_profiles	List server profiles
POST	/server_profiles	Create a profile
GET	/server_profiles/{id}	Get profile details
PUT	/server_profiles/{id}	Update a profile
DELETE	/server_profiles/{id}	Delete a profile
POST	/server_profiles/{id}/clone	Clone a profile
POST	/server_profiles/estimate-cost	Estimate cost for config

Analytics

Method	Path	Description
GET	/analytics/concurrent-users	Concurrent user counts over time
GET	/analytics/quality-stats	Session quality statistics
GET	/analytics/problematic	Problematic sessions
GET	/analytics/performance-bottlenecks	Performance bottleneck analysis
GET	/analytics/cpu-distribution	CPU usage distribution
GET	/analytics/quality-alerts	Quality alert list
GET	/projects/{id}/analytics/quality-history	Project quality history

Billing

Method	Path	Description
GET	/billing/balance	Get credit balance in USD
GET	/billing/credits	List all credit pools with balances
GET	/billing/invoices	List invoices from Stripe

Tokens

Method	Path	Description
GET	/tokens	List session tokens
POST	/tokens	Create a session token
GET	/tokens/{id}	Get token details

Full API Documentation

For complete interactive API documentation with request/response schemas:

Interactive API Docs

Need Help?

• Browse the interactive API documentation
• Check the Getting Started guide
• Contact support for assistance