---
title: "Homarr API — Programmatic Dashboard Management"
aliases: [homarr-api, homarr-rest-api]
tags: [homelab, homarr, api, self-hosted, dashboard, automation]
sources: [raw/Homarr documentation.md]
created: 2026-04-19
updated: 2026-04-19
---

Homarr (v1.59.2) exposes a full OpenAPI + tRPC API for programmatic control of your homelab dashboard. Use it to sync apps from container orchestration, automate integrations, or build custom tooling on top.

## API Access

- Navigate to **Management → Tools → API** in the Homarr UI to open the Swagger/OpenAPI spec
- The spec follows the OpenAPI 3.1 standard
- The JSON schema URL: `/api/open-api-schema.json`
- Can be loaded into Postman, Insomnia, or Hoppscotch for testing

## Authentication

### API Keys
- Create keys from the **Authentication** tab in the Homarr UI
- Keys **do not expire** — usable indefinitely
- Format: `<id>.<token>` (e.g. `abc123def456.xyz789tokenvalue...`)
- Pass in the `ApiKey` header:

```bash
ApiKey: abc123def456.xyz789tokenvalue...
```

- Falls back to session cookie auth if no key is provided (browser-based access)

### Supported Endpoint Types

| Endpoint Type | Path Pattern | API Key Support |
|---------------|--------------|-----------------|
| OpenAPI | `/api/...` | Supported |
| tRPC | `/api/trpc/...` | Supported |

## 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

- Sync Homarr app definitions from a Kubernetes/Docker cluster automatically
- CI/CD pipelines that update dashboard entries on deploy
- Dynamically add/remove integrations based on replica count
- Custom monitoring dashboards that read from Homarr state
- Automation scripts for homelab maintenance

## Key Takeaways

- Homarr API is **OpenAPI 3.1** — any standard OpenAPI client works
- API keys are **non-expiring** and support both `/api/` and `/api/trpc/` paths
- Key use case: **container orchestration sync** — auto-update dashboard when services scale
- The spec is self-hosted; access it at `Management → Tools → API` on your Homarr instance
- Language-neutral — implement in any language with basic HTTP/JSON support

## Related Articles

- [[wiki/homelab/home-server-101|Home Server 101 — Beginner's Guide to Self-Hosting]]
- [[wiki/homelab/homelab-from-scratch-budget-build|Homelab From Scratch — Budget-First Design]]
- [[wiki/homelab/bigibz1-homelab-hardware|bigibz1 Homelab Hardware Reference]]
- [[wiki/architecture/docker-compose-patterns|Docker Compose Patterns]]

## Sources

- `raw/Homarr documentation.md` — official Homarr API docs, version 1.59.2
