Skip to main content

​
Overview

Homarr provides a comprehensive API built on tRPC, enabling type-safe communication between the client and server. The API supports both HTTP requests and WebSocket connections for real-time updates.

​
API Architecture

​
tRPC Overview

Homarr uses tRPC to provide:
  • End-to-end type safety - Full TypeScript types from server to client
  • Automatic validation - Input validation using Zod schemas
  • Efficient data transfer - Using SuperJSON for serialization
  • Real-time capabilities - WebSocket subscriptions for live updates

​
Main API Routers

The Homarr API is organized into the following main routers:
RouterPurpose
boardBoard management, layouts, and permissions
appApplication management and retrieval
widgetWidget-specific data and operations
userUser account and profile management
integrationIntegration management and testing
groupUser group management
apiKeysAPI key generation and management
inviteUser invitation system
serverSettingsServer configuration
dockerDocker container management
kubernetesKubernetes cluster integration
mediaMedia file management
iconIcon search and retrieval

​
Accessing the API

The Homarr API can be accessed in three ways: For TypeScript/JavaScript applications, use the tRPC client: 
import { api } from "~/trpc/react";

// Query example
const { data: boards } = api.board.getAllBoards.useQuery();

// Mutation example
const createBoard = api.board.createBoard.useMutation();
await createBoard.mutateAsync({
  name: "MyBoard",
  columnCount: 12,
  isPublic: false,
});

​
2. HTTP REST API

Some endpoints are exposed via OpenAPI-compatible REST endpoints: 
curl -X GET https://your-homarr-instance.com/api/apps \
  -H "Authorization: Bearer YOUR_API_KEY"

​
3. WebSocket Connection

For real-time updates, connect to the WebSocket server: 
// WebSocket connection on port 3001
const wsClient = createWSClient({
  url: "ws://localhost:3001",
});

​
API Versioning

The Homarr API is currently in active development. Breaking changes may occur between major versions.
Currently, Homarr does not use explicit API versioning. The API evolves with the application version. Check the changelog for API changes between releases.

​
Rate Limiting

Homarr does not currently implement rate limiting at the API level. However, certain operations may have built-in throttling or caching:
  • Widget data requests are cached to prevent excessive API calls to external services
  • Integration test connections are debounced
  • Real-time subscriptions use intelligent polling intervals

​
Error Handling

The API uses tRPC error codes:
Error CodeDescription
UNAUTHORIZEDUser is not authenticated
FORBIDDENUser lacks required permissions
NOT_FOUNDResource does not exist
BAD_REQUESTInvalid input parameters
CONFLICTResource already exists
INTERNAL_SERVER_ERRORServer-side error

​
Error Response Format

{
  error: {
    code: "FORBIDDEN",
    message: "Permission denied",
    data: {
      zodError: null, // Zod validation errors if applicable
      path: "board.createBoard",
      stack: "..." // Only in development
    }
  }
}

​
Next Steps

Authentication

Learn how to authenticate API requests

Boards API

Manage boards and layouts

Widgets API

Access widget data and subscriptions

WebSocket API

Real-time updates via WebSocket

Build docs developers (and LLMs) love

Get started for freeTalk to us