89 lines
3.3 KiB
Plaintext
89 lines
3.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
|
|
|
|
## 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, automatic mobile layout mode, and status behavior
|
|
- Configure saved responsive layouts through Homarr's board settings UI when a server uses legacy mobile layout mode
|
|
|
|
Use the interactive API reference to inspect the exact request body for OpenAPI endpoints under the `boards` and
|
|
`settings` tags. Saved responsive layouts are intentionally not exposed as an OpenAPI or MCP replacement operation
|
|
because omitting a layout would remove it.
|