support@jyv.ai
The Intelligent Audio Layer™
Documentation

API Reference

Reference

API Reference

REST API for integrating Jyv Desktop with your applications, workflows, and automation tools.

10 min readUpdated December 2025

Overview

The Jyv Desktop API allows you to programmatically control audio settings, switch profiles, and integrate Jyv with your custom applications and workflows.

Base URL: http://localhost:3842/api/v1

The API runs locally on your machine. For remote access, see our Enterprise documentation.

Common use cases:

  • Build custom dashboards for audio control
  • Integrate with home automation systems
  • Create Stream Deck plugins
  • Automate audio switching based on external events
  • Build team collaboration tools

Authentication

Jyv Desktop API uses API keys for authentication. Generate your key in the application:

  1. Generate API key

    Open Jyv Desktop → Settings → Developer → API Access

    Click Generate New API Key and copy the key.

  2. Use in requests

    Include the API key in the Authorization header of all requests:

    curl -X GET http://localhost:3842/api/v1/profiles \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Security: API keys grant full control over Jyv Desktop. Never commit them to version control or share them publicly. Use environment variables:

# .env file
JYV_API_KEY=your_api_key_here

Profiles API

List all profiles

Get all saved audio profiles:

GET /profiles
Response
{
  "profiles": [
    {
      "id": "prof_abc123",
      "name": "Work Calls",
      "active": true,
      "settings": {
        "noiseSuppressionLevel": 80,
        "voiceEnhancement": true
      },
      "createdAt": "2025-12-01T10:00:00Z",
      "updatedAt": "2025-12-08T15:30:00Z"
    }
  ]
}

Get active profile

GET /profiles/active

Create new profile

POST /profiles
                        
{
  "name": "Gaming",
  "settings": {
    "noiseSuppressionLevel": 60,
    "voiceEnhancement": false,
    "appVolumes": {
      "discord.exe": 100,
      "game.exe": 70,
      "spotify.exe": 40
    }
  },
  "automation": {
    "triggers": [
      {
        "type": "app_launch",
        "app": "steam.exe"
      }
    ]
  }
}
Response
{
  "id": "prof_xyz789",
  "name": "Gaming",
  "created": true
}

Activate profile

POST /profiles/{profile_id}/activate
Example
curl -X POST http://localhost:3842/api/v1/profiles/prof_abc123/activate \
  -H "Authorization: Bearer YOUR_API_KEY"

Update profile

PATCH /profiles/{profile_id}
                        
{
  "name": "Work Calls (Updated)",
  "settings": {
    "noiseSuppressionLevel": 85
  }
}

Delete profile

DELETE /profiles/{profile_id}

Audio Control API

Get current audio state

GET /audio/state
Response
{
  "masterVolume": 80,
  "micMuted": false,
  "runningApps": [
    {
      "name": "spotify.exe",
      "volume": 65,
      "muted": false,
      "outputDevice": "Headphones"
    },
    {
      "name": "discord.exe",
      "volume": 100,
      "muted": false,
      "outputDevice": "Headphones"
    }
  ]
}

Set app volume

POST /audio/volume
                        
{
  "app": "spotify.exe",
  "volume": 50
}

Mute/unmute app

POST /audio/mute
                        
{
  "app": "spotify.exe",
  "muted": true
}

Set microphone state

POST /audio/microphone
                        
{
  "muted": false,
  "noiseSuppressionLevel": 70,
  "voiceEnhancement": true
}

Route app to output device

POST /audio/route
                        
{
  "app": "discord.exe",
  "outputDevice": "Headphones"
}

Webhooks

Configure Jyv to send HTTP requests when events occur:

Available events

  • profile.switched - When profile changes
  • app.volume_changed - When app volume is adjusted
  • microphone.muted - When mic is muted/unmuted
  • meeting.started - When Jyv detects a meeting starting
  • meeting.ended - When meeting ends

Configure webhook

POST /webhooks
                        
{
  "url": "https://your-server.com/jyv-events",
  "events": ["profile.switched", "meeting.started"],
  "secret": "your_webhook_secret"
}

Webhook payload example

{
  "event": "profile.switched",
  "timestamp": "2025-12-08T15:30:00Z",
  "data": {
    "previousProfile": "Work Calls",
    "currentProfile": "Gaming",
    "triggeredBy": "app_launch",
    "trigger": "steam.exe"
  }
}

Rate Limits

API requests are rate limited to ensure system stability:

  • Free tier: 60 requests/minute
  • Pro tier: 300 requests/minute
  • Enterprise: Custom limits (contact sales)

Rate limit information is included in response headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1702047600

When rate limited, you'll receive a 429 status code:

{
  "error": "Rate limit exceeded",
  "retryAfter": 30
}

SDKs & Libraries

Official SDKs

JavaScript/TypeScript
npm install @jyv/desktop-sdk

import { JyvDesktop } from '@jyv/desktop-sdk';

const jyv = new JyvDesktop({ apiKey: process.env.JYV_API_KEY });

// Switch profile
await jyv.profiles.activate('prof_abc123');

// Set app volume
await jyv.audio.setVolume('spotify.exe', 50);

// Listen for events
jyv.on('profile.switched', (data) => {
  console.log('Switched to:', data.currentProfile);
});
Python
pip install jyv-desktop

from jyv_desktop import JyvDesktop

jyv = JyvDesktop(api_key=os.environ['JYV_API_KEY'])

# Switch profile
jyv.profiles.activate('prof_abc123')

# Set app volume
jyv.audio.set_volume('spotify.exe', 50)

# Get current state
state = jyv.audio.get_state()
print(state['runningApps'])

Community libraries

  • Go: github.com/jyv-community/jyv-go
  • Rust: crates.io/crates/jyv-desktop
  • C#: NuGet: JyvDesktop.NET

Community libraries are maintained by users. For official support, use JavaScript or Python SDKs.

Example integrations

Check out our examples repository for:

  • Stream Deck plugin
  • Home Assistant integration
  • Elgato Wave Link alternative
  • Discord bot for team audio control
  • OBS script for automatic profile switching

Related Documentation

Slack Integration

Connect Jyv with Slack webhooks

→

Automations

Create custom automation rules

→

Audio Profiles

Manage profiles programmatically

→

Need more help?

Can't find what you're looking for? Our support team is here to help.

Contact SupportJoin Community