Getting Started

Aviato exposes three integration surfaces. They share the same event vocabulary and the same data model, but each is suited to a different shape of integration. Pick the right one before you start writing code.

Most non trivial integrations end up combining two of these: a webhook to learn that an event happened, plus a REST call to fetch more detail. A plugin can register internal handlers and emit its own events that webhooks then deliver, so the line between the three is intentionally porous.

Plugins

A plugin is a long lived process that Aviato launches, supervises, and talks to over JSON-RPC 2.0 on stdio. Plugins can be written in Bun, Node, Python, or shipped as a binary, and they declare what they want to do via a manifest. Once registered they show up in Settings → Plugins with status, logs, and config.

Reach for a plugin when:

• You want to add a new metadata source (an indexer that calls a third party API).
• You want to enrich files at scan time (a hook that reads tags, generates thumbnails, transcribes audio).
• You want to extend the web UI with new panels or routes.
• The integration needs to be installable by other Aviato users, not just configured for one server.

If your code mostly reacts to things happening in Aviato and lives elsewhere, you probably want a webhook instead. If it mostly queries or mutates Aviato from another system, you want the REST API.

Start here:

• Plugin getting started
• Plugin manifest
• Indexer plugins and hook plugins

Webhooks

A webhook is a URL plus an event filter. When a matching event fires inside Aviato, the server POSTs a JSON payload to the URL. Payloads are signed with HMAC SHA256 when you configure a secret, and every attempt is recorded in a delivery log you can inspect from the UI.

Reach for a webhook when:

• You already have an HTTP service (Slack, Discord, n8n, Zapier, a custom worker) and you just want to know when something happens.
• You want a low coupling integration that survives Aviato upgrades. The event registry is stable; new events are added, old ones are not removed.
• You want one place to fan out events to several systems without reimplementing the event subscription each time.

Webhooks subscribe to the same event registry as plugins, so any new event added to the system is automatically deliverable.

Start here:

• Webhooks

REST API

The REST API is the same surface the Aviato web app talks to. It is fully described by an OpenAPI 3.1 spec, generated from @hono/zod-openapi route definitions. There is no separate "public" vs "internal" API: anything the UI does, you can do.

Reach for the REST API when:

• You are building a client (mobile app, desktop helper, command line tool).
• You want to script bulk operations (import, re tag, refresh metadata for a library).
• You need to read state on demand rather than reacting to events.

You authenticate with an API key, which you create from Settings → API Keys. API keys are bearer tokens prefixed with avt_ and they grant admin level access, so treat them like a password.

Start here:

• API Overview
• Interactive reference at /api/docs on a running server (loaded from the live OpenAPI spec)

Picking a surface

A few rules of thumb:

• "Something just happened in Aviato and I want to do X about it elsewhere." → Webhook.
• "I want Aviato to do something it does not currently do." → Plugin.
• "I want another system to read or change Aviato state on demand." → REST API.
• "I want to ship this to other Aviato users." → Plugin (it is the only surface with an installable lifecycle).

If you are still unsure, start with a webhook plus the REST API. That combination is enough for almost every external integration and avoids the longer feedback loop of plugin development.