Integrations API

Overview

The Integrations API manages connections to external services like media servers, download clients, home automation systems, and monitoring tools.

Queries

all

Get all integrations accessible to the current user.

const integrations = await api.integration.all.query();

Authentication: Protected Response:

string

Integration unique identifier

name

string

Integration display name

kind

string

Integration type (e.g., “plex”, “sonarr”, “radarr”)

url

string

Integration base URL

permissions

object

User’s permissions for this integration

hasUseAccess

boolean

Can use the integration in widgets

hasInteractAccess

boolean

Can interact with the integration (e.g., control devices)

hasFullAccess

boolean

Full access including management and deletion

allOfGivenCategory

Get integrations by category.

const mediaIntegrations = await api.integration.allOfGivenCategory.query({
  category: "mediaServer",
});

Parameters:

allThatSupportSearch

Get integrations that support search functionality.

const searchIntegrations = await api.integration.allThatSupportSearch.query();

search

Search integrations by name.

const results = await api.integration.search.query({
  query: "plex",
  limit: 10,
});

byId

Get detailed integration information.

const integration = await api.integration.byId.query({
  id: "integration-id",
});

Permission Required: Integration full access Response:

string

Integration ID

name

string

Integration name

kind

string

Integration kind

url

string

Integration URL

secrets

array

Integration secrets (passwords are hidden)

kind

string

Secret type (e.g., “apiKey”, “username”, “password”)

value

string | null

Secret value (only shown for public secrets like usernames)

updatedAt

Date

Last update timestamp

app

object | null

Associated app information

byIds

Get multiple integrations by IDs.

const integrations = await api.integration.byIds.query([
  "integration-id-1",
  "integration-id-2",
]);

Authentication: Public Returns: Only id and kind fields

getIntegrationPermissions

Get permission configuration for an integration.

const permissions = await api.integration.getIntegrationPermissions.query({
  id: "integration-id",
});

Permission Required: Integration full access

Mutations

create

Create a new integration.

const result = await api.integration.create.mutate({
  name: "My Plex Server",
  kind: "plex",
  url: "https://plex.example.com",
  secrets: [
    {
      kind: "apiKey",
      value: "your-plex-token",
    },
  ],
  app: {
    name: "Plex",
    description: "Media Server",
    iconUrl: "https://cdn.jsdelivr.net/gh/walkxcode/dashboard-icons/svg/plex.svg",
    href: "https://plex.example.com",
    pingUrl: null,
  },
  attemptSearchEngineCreation: true,
});

Permission Required: integration-create Parameters:

name

string

required

Display name for the integration

kind

string

required

Integration type (see available kinds below)

url

string

required

Base URL of the service

secrets

array

required

Authentication secrets

app

object

Associated app (creates new app or links to existing)

attemptSearchEngineCreation

boolean

Auto-create search engine if integration supports search

Process:

Tests connection to the service
Validates credentials
Creates integration if test succeeds
Optionally creates associated app
Optionally creates search engine entry

Returns:

error

object | undefined

Error details if connection test failed

Common Integration Kinds:

Media: plex, jellyfin, emby
*arr Apps: sonarr, radarr, lidarr, readarr, prowlarr
Downloads: qBittorrent, transmission, deluge, sabnzbd
Media Requests: overseerr, jellyseerr
DNS: pihole, adguardHome
Smart Home: homeAssistant
Other: tdarr, healthchecks, coolify

update

Update an existing integration.

const result = await api.integration.update.mutate({
  id: "integration-id",
  name: "Updated Name",
  url: "https://new-url.example.com",
  secrets: [
    {
      kind: "apiKey",
      value: "new-api-key", // Provide value to update
    },
    {
      kind: "username",
      value: null, // Keep existing value
    },
  ],
  appId: "app-id",
});

Permission Required: Integration full access Parameters:

string

required

Integration ID

name

string

required

Updated name

url

string

required

Updated URL

secrets

array

required

Secrets to update (set value to null to keep existing)

appId

string

Link to different app

Notes:

Tests connection before applying changes
Only updates secrets where value is not null
Can add new secrets or remove existing ones

delete

Delete an integration.

await api.integration.delete.mutate({ id: "integration-id" });

Permission Required: Integration full access

Deleting an integration will break any widgets that depend on it.

saveUserIntegrationPermissions

Configure user-specific permissions.

await api.integration.saveUserIntegrationPermissions.mutate({
  entityId: "integration-id",
  permissions: [
    {
      principalId: "user-id-1",
      permission: "use",
    },
    {
      principalId: "user-id-2",
      permission: "interact",
    },
  ],
});

Permission Required: Integration full access Permission Levels:

use - Can use in widgets
interact - Can use and control (e.g., control smart home devices)
full - Full access including management

saveGroupIntegrationPermissions

Configure group-specific permissions.

await api.integration.saveGroupIntegrationPermissions.mutate({
  entityId: "integration-id",
  permissions: [
    {
      principalId: "group-id",
      permission: "use",
    },
  ],
});

searchInIntegration

Search within an integration that supports search.

const results = await api.integration.searchInIntegration.query({
  integrationId: "integration-id",
  query: "search term",
});

Requirements:

Integration must support search category
User must have use or higher permission

Integration Secrets

Secret Types

Different integrations require different authentication methods:

API Key

{
  kind: "apiKey",
  value: "your-api-key",
}

Username + Password

[
  { kind: "username", value: "admin" },
  { kind: "password", value: "secure-password" },
]

Token

{
  kind: "token",
  value: "bearer-token",
}

Security

Secrets are encrypted at rest using AES encryption
Private secrets (passwords, API keys) are never returned in API responses
Public secrets (usernames) are visible in responses
Only users with full access can view/modify secrets

Testing Connections

Integrations are automatically tested during creation and updates:

try {
  const result = await api.integration.create.mutate({ ... });
  
  if (result?.error) {
    console.error('Connection test failed:', result.error);
  } else {
    console.log('Integration created successfully');
  }
} catch (error) {
  console.error('Failed to create integration:', error);
}

Test Process:

Validates URL is accessible
Tests authentication credentials
Verifies API compatibility
Returns detailed error if test fails

Common Test Errors:

CONNECTION_REFUSED - Service is unreachable
INVALID_CREDENTIALS - Authentication failed
UNSUPPORTED_VERSION - API version mismatch
TIMEOUT - Request took too long

Examples

Create Plex Integration

const result = await api.integration.create.mutate({
  name: "Home Plex Server",
  kind: "plex",
  url: "https://plex.example.com",
  secrets: [
    {
      kind: "apiKey",
      value: "your-plex-token",
    },
  ],
  app: {
    name: "Plex",
    description: "Home Media Server",
    iconUrl: "https://cdn.jsdelivr.net/gh/walkxcode/dashboard-icons/svg/plex.svg",
    href: "https://plex.example.com",
    pingUrl: "https://plex.example.com/identity",
  },
});

if (result?.error) {
  console.error('Failed to connect to Plex:', result.error);
} else {
  console.log('Plex integration created successfully!');
}

Create Home Assistant Integration

await api.integration.create.mutate({
  name: "Home Assistant",
  kind: "homeAssistant",
  url: "https://homeassistant.local:8123",
  secrets: [
    {
      kind: "apiKey",
      value: "your-long-lived-access-token",
    },
  ],
  app: {
    name: "Home Assistant",
    description: "Smart Home Hub",
    iconUrl: "https://cdn.jsdelivr.net/gh/walkxcode/dashboard-icons/svg/home-assistant.svg",
    href: "https://homeassistant.local:8123",
    pingUrl: null,
  },
});

Rotate Integration Credentials

// Get current integration
const integration = await api.integration.byId.query({
  id: "integration-id",
});

// Update with new credentials
await api.integration.update.mutate({
  id: integration.id,
  name: integration.name,
  url: integration.url,
  secrets: [
    {
      kind: "apiKey",
      value: "new-api-key", // New credential
    },
  ],
});

Overview

tRPC API

WebSocket

Integrations API

Overview

Queries

all

allOfGivenCategory

allThatSupportSearch

search

byId

byIds

getIntegrationPermissions

Mutations

create

update

delete

saveUserIntegrationPermissions

saveGroupIntegrationPermissions

searchInIntegration

Integration Secrets

Secret Types

API Key

Username + Password

Token

Security

Testing Connections

Examples

Create Plex Integration

Create Home Assistant Integration

Rotate Integration Credentials

Build docs developers (and LLMs) love

Overview

tRPC API

WebSocket

​Overview

​Queries

​all

​allOfGivenCategory

​allThatSupportSearch

​search

​byId

​byIds

​getIntegrationPermissions

​Mutations

​create

​update

​delete

​saveUserIntegrationPermissions

​saveGroupIntegrationPermissions

​searchInIntegration

​Integration Secrets

​Secret Types

​API Key

​Username + Password

​Token

​Security

​Testing Connections

​Examples

​Create Plex Integration

​Create Home Assistant Integration

​Rotate Integration Credentials

Build docs developers (and LLMs) love

Overview

Queries

all

allOfGivenCategory

allThatSupportSearch

search

byId

byIds

getIntegrationPermissions

Mutations

create

update

delete

saveUserIntegrationPermissions

saveGroupIntegrationPermissions

searchInIntegration

Integration Secrets

Secret Types

API Key

Username + Password

Token

Security

Testing Connections

Examples

Create Plex Integration

Create Home Assistant Integration

Rotate Integration Credentials