175 lines
8.3 KiB
Plaintext
175 lines
8.3 KiB
Plaintext
---
|
|
title: API
|
|
tags:
|
|
- API
|
|
- Development
|
|
- Interface
|
|
---
|
|
|
|
Using the Homarr API, you can interface with the application with your own code and business logic.
|
|
It enables you to trigger almost all actions that you can perform from the Homarr UI.
|
|
With the API, you can build resilient systems that automatically update Homarr with data - for example syncing it with
|
|
your deployments in a cluster or dynamically adding integrations depending on how many replicas you run.
|
|
|
|
This page is language-neutral, and you must implement the API on your own in your desired language.
|
|
It requires you to know your programming language well and have a basic understanding of HTTP, JSON and networking.
|
|
You can test out API endpoints using any OpenAPI client - for example [Yaak](https://yaak.app/).
|
|
|
|
## Opening the API specification
|
|
|
|
The specification is implemented according to the OpenAPI standard.
|
|
To access the documentation, you'll need to spin up an instance of Homarr.
|
|
Navigate to `Management` > `Tools` > `API`.
|
|
You can copy the JSON url into your OpenAPI client or try out the endpoints directly from your browser.
|
|
|
|
Alternatively, you can [open the full interactive API reference](/api-reference) directly in your browser.
|
|
|
|
## Authentication
|
|
|
|
Many endpoints will require you to authenticate. At the top of the API reference, you'll find a button to authenticate yourself with an API key.
|
|
You can obtain API keys from the "Authentication" tab at the top of the page.
|
|
API keys will not expire and can be used indefinitely.
|
|
|
|
### API Key Format
|
|
|
|
API keys are provided in the format `<id>.<token>`. When making requests, include the key in the `ApiKey` header:
|
|
|
|
```
|
|
ApiKey: abc123def456.xyz789tokenvalue...
|
|
```
|
|
|
|
### Supported Endpoints
|
|
|
|
API key authentication works with both endpoint types:
|
|
|
|
| Endpoint Type | Path Pattern | API Key Support |
|
|
| ------------- | --------------- | --------------- |
|
|
| OpenAPI | `/api/...` | ✅ Supported |
|
|
| tRPC | `/api/trpc/...` | ✅ Supported |
|
|
|
|
If no API key is provided, Homarr falls back to session cookie authentication (for browser-based access).
|
|
|
|
### Usage Examples
|
|
|
|
**OpenAPI endpoint:**
|
|
|
|
```bash
|
|
curl -H 'ApiKey: <id>.<token>' http://localhost:7575/api/health/live
|
|
```
|
|
|
|
**tRPC endpoint:**
|
|
|
|
```bash
|
|
curl -H 'ApiKey: <id>.<token>' http://localhost:7575/api/trpc/app.all
|
|
```
|
|
|
|
### Use Cases
|
|
|
|
API key authentication enables programmatic access for:
|
|
|
|
- Automation scripts and CI/CD pipelines
|
|
- Third-party integrations
|
|
- Custom dashboards and monitoring tools
|
|
- Container orchestration systems that need to sync app definitions
|
|
|
|
## Permissions
|
|
|
|
API keys act as the user that created them, so every request is subject to that user's group
|
|
permissions. A call that the user is not allowed to make returns `FORBIDDEN`, and list endpoints
|
|
return only the records the user may see rather than failing.
|
|
|
|
### App endpoints require app management access
|
|
|
|
`GET /api/apps`, `GET /api/apps/paginated` and `GET /api/apps/search` (tRPC `app.all`,
|
|
`app.getPaginated`, `app.search`) require the **modify all apps** permission. They previously
|
|
returned the full app catalogue — including internal URLs — to any authenticated user.
|
|
|
|
If a script that used to work now returns `FORBIDDEN`, grant **modify all apps** to a group the key
|
|
owner belongs to, or switch to `GET /api/apps/selectable`, which returns the reduced fields used by
|
|
board pickers.
|
|
|
|
### Integration endpoints are filtered per key
|
|
|
|
`integration.all`, `integration.allThatSupportSearch`, `integration.allOfGivenCategory` and
|
|
`integration.search` filter server side. Without a global integration permission, a key only
|
|
receives the integrations its owner has been granted access to, so responses may contain fewer
|
|
records than before rather than returning an error. `integration.search` applies its `limit` after
|
|
filtering, so a scoped key still receives a full page of results.
|
|
|
|
Each returned integration carries a `permissions` object — check `hasUseAccess` before reading data
|
|
and `hasInteractAccess` before performing actions; `false` means the key owner lacks that level for
|
|
that integration, not that the call failed.
|
|
|
|
## Board Automation
|
|
|
|
The OpenAPI and MCP APIs include board management endpoints for common automation workflows:
|
|
|
|
- Create, duplicate, rename and delete boards
|
|
- Change board visibility
|
|
- Update board visual and behavior settings
|
|
- Set desktop and mobile home boards for the current user
|
|
- Configure global board defaults such as public home boards and status behavior
|
|
|
|
Board layout responses identify each layout with a `mobile`, `base`, or `custom` role. Mobile and Base are protected. Layout-saving clients must preserve existing roles, keep Mobile at breakpoint `0`, keep Base as the highest breakpoint, and use unique custom breakpoints between them. The layout save operation returns the canonical saved layouts, including server-generated IDs for new custom layouts. A non-Base layout can be regenerated from Base with the protected reset operation.
|
|
|
|
Use the interactive API reference to inspect the exact request body for each endpoint under the `boards` and `settings` tags.
|
|
|
|
## Docker action payload migration
|
|
|
|
Docker lifecycle and removal actions now identify each container with both its Docker endpoint and container ID. This is a
|
|
breaking change for tRPC and MCP clients that previously sent an `ids` array to the start, stop, restart, or remove action.
|
|
|
|
Replace the old payload:
|
|
|
|
```json
|
|
{ "ids": ["container-id"] }
|
|
```
|
|
|
|
with endpoint-qualified targets:
|
|
|
|
```json
|
|
{
|
|
"targets": [{ "endpointId": "local", "id": "container-id" }]
|
|
}
|
|
```
|
|
|
|
Read `endpointId` and `id` from `docker.getContainers` (MCP tool `docker_getContainers`) immediately before the action.
|
|
Pass those pairs unchanged to `docker.startAll`, `docker.stopAll`, `docker.restartAll`, or `docker.removeAll`; their MCP tool
|
|
names use underscores, such as `docker_restartAll`. Endpoint qualification prevents identical container IDs on different
|
|
Docker or Podman endpoints from targeting the wrong service.
|
|
|
|
`docker.getContainers` also accepts an optional `endpointIds` array. Omit it or pass an empty array to query every configured
|
|
Docker environment, or pass one or more IDs returned by `docker.getEndpoints` to query only those Dockerode clients. The
|
|
Docker widget uses the same behavior for its environment selector.
|
|
|
|
## Partial integration failures
|
|
|
|
Multi-integration widget queries keep data from integrations that remain available. Calendar and media-server results include
|
|
an optional `error` on a failed integration; media-request responses expose a `failedIntegrations` array, and the latest
|
|
requests endpoint returns its items in `requests`. When every selected integration fails, the query returns an error instead
|
|
of a partial response.
|
|
|
|
Other widgets use the same settlement pattern with endpoint-specific shapes: a failed integration may appear as a named
|
|
fallback row, in a failure array, or be omitted while healthy results remain. Widget pages should identify the shape they
|
|
render rather than assuming every query exposes an `error` field.
|
|
|
|
### Saving dashboard layouts
|
|
|
|
The dashboard editor saves item positions and sections as one board update.
|
|
Canvas height follows its content automatically and does not require a separate API setting.
|
|
Responsive layouts store optional left and right gutter widths from zero to three columns.
|
|
Gutter columns are reserved from the layout's total column count, and changing them reflows affected items.
|
|
|
|
## Get Custom Widget authoring resources
|
|
|
|
Custom JSX v2 provides four HTTP discovery endpoints:
|
|
|
|
- `GET /api/custom-widgets/authoring-prompt` returns the current prompt plus MCP and HTTP resource identifiers.
|
|
- `GET /api/custom-widgets/schema` returns the canonical widget JSON Schema.
|
|
- `GET /api/custom-widgets/components` returns the release-matched static component catalog.
|
|
- `GET /api/custom-widgets/skill` returns the concise live `SKILL.md` plus skills.sh, source, and install metadata. Retrieve the schema, component catalog, and examples through their dedicated resources only when needed.
|
|
|
|
Call `customWidget_configurationRequestUser` to create a temporary API source setup URL where the user can confirm their server URL and enter credentials. Do not construct or save this URL.
|
|
|
|
Authenticated tRPC and MCP procedures support definition management, validation, previews, template patches, and credential writes. An exported definition does not contain credentials.
|