API

Use the generated specification under Management → Tools → API or the interactive API reference. This page covers contracts that are not obvious from those schemas. The in-app reference loads its schema from /api/openapi?format=scalar on your Homarr instance. /api/openapi provides the raw JSON specification.

REST exposes selected existing Homarr controls. Use tRPC for advanced operations; both accept the ApiKey header. PUT /api/boards/{id}/content uses the dashboard editor's complete sections and items arrays. Omitted entries are removed, so read the current content through tRPC board.getBoardByName before editing it. Widget movement and resizing can instead use the existing item-layout endpoint.

Use GET /api/users/preferences and PATCH /api/users/preferences to read or change preferences. Send only changed values: { "colorScheme": "light" } or { "headerPreferences": { "visible": false } }. Omitted values stay unchanged; null clears nullable board/search references. Header fields merge; supplied zone arrays replace their zone. Omit userId for yourself; another user requires admin permission. Older preference routes remain available.

Authentication and browser access

API keys are shown once as <id>.<token>. Send one in the ApiKey header; it acts as its creator and does not expire. tRPC accepts the same header. Same-origin browser requests can use the Homarr session cookie.

Cross-origin browser requests require ApiKey; they do not use session cookies. Reverse proxies must forward OPTIONS and preserve CORS headers. An HTTPS API reference cannot call an HTTP-only instance because browsers block mixed content.

Endpoint constraints

• General pagination and shared search are capped at 100 records.
• POST /api/invites and invite.createInvite accept expirationDate as a timezone-qualified ISO 8601 string.
• GET /api/health/live is unauthenticated and returns 200 when all dependencies are healthy, 500 otherwise.

widget.immich.getAlbumPreview returns at most one image from a selected album. Its input includes albumId and randomizePhotos; it uses the same saved-integration access rules as widget.immich.getAlbum. Use getAlbum for the complete album image list.

Permissions and results

Requests use the API key owner's permissions. Unauthorized operations return FORBIDDEN; resource-aware lists are filtered on the server.

app.all, app.getPaginated, and app.search require Modify all apps because they include internal URLs. Use app.selectable for reduced picker data. Integration lists include only accessible integrations; check hasUseAccess and hasInteractAccess before reading data or invoking actions.

Multi-integration queries can return partial data with endpoint-specific failure metadata.

Board automation

Each board has one Base and one Mobile layout; Mobile uses breakpoint 0. Other breakpoints must be unique, and Homarr uses the highest breakpoint that fits. Reuse canonical layouts and generated IDs returned by save operations.

Integration-backed widgets require use access to each newly selected integration.

board.addItem accepts size: { width, height } in grid cells (1–24 each), places the item in the first free position on every layout, and caps width to the available columns.

board.updateItemLayout (PATCH /api/boards/{boardId}/items/{itemId}/layouts/{layoutId}) moves or resizes one item in one layout without replacing the board. It cannot move the item outside its section or overlap another item/container.

Root CA automation

Administrators can inspect a named CA with GET /api/certificates/{fileName} (certificates.getCertificate) or create it with POST /api/certificates/root (certificates.ensureRootCertificate), using JSON { fileName, certificate }. Names are limited to 128 characters, start with a letter or digit, contain only letters, digits, dots, underscores and hyphens, and end in .crt or .pem. Supply one currently valid self-signed PEM root CA, at most 64 KiB, without a chain or private key.

Inspection returns public metadata or null when absent. Creation returns { created, certificate }; identical PEM bytes return created: false, while different existing bytes or unsafe file paths return CONFLICT without replacement. sha256 hashes the exact UTF-8 PEM bytes, including whitespace; fingerprint256 identifies the DER certificate. Dates are ISO 8601. Certificate contents are never returned. Expired stored roots remain inspectable. Trust applies to subsequent integration requests without a restart; it does not bypass hostname verification.

Docker targets

Docker actions require { endpointId, id } targets from docker.getContainers; endpointId distinguishes hosts. Omit endpointIds or pass an empty array to query every configured endpoint.

Custom Widget resources

Administrators can retrieve the Custom Widget authoring prompt, schema, component catalog, skill, and references under /api/custom-widgets/. See agent authoring for the workflow.

Call any integration API endpoint

POST /api/integrations/request is available as tRPC integration.request and MCP integration_request. Homarr uses the saved integration credentials; callers do not supply them. The path stays within the saved integration URL, and redirects are rejected. See the generated schema for selectors, permissions, and request limits.

Even GET can change upstream state. Homarr 200 can contain an upstream failure; inspect ok, status, and data. Requests are not retried, so check upstream state after a timeout before retrying a write.

The iCalendar feed integration stores a calendar URL rather than arbitrary HTTP API credentials. TrueNAS uses a WebSocket API. Neither works with integration_request or Custom Widget integration sources. qBittorrent generic requests require a saved API key and qBittorrent 5.2.0 or newer. UniFi generic requests require the controller's HTTPS URL and actual port.