Introducing a new way to review your PRs.

Read the announcement

immich-app / immich

High performance self-hosted photo and video management solution.

View on GitHub

21 documents · Updated Oct 19, 2026

docs / developer-contracts-and-extension-ecosystem

Developer contracts and extension ecosystem

Immich gives external tools two main ways to work with the product: a typed HTTP API and a workflow-based plugin system. The API supports reusable clients such as the TypeScript SDK and command-line client. Plugins add event-driven filters and actions that can change assets or call approved outside services. For deployment and end-to-end validation, see Deployment and end-to-end validation. For the server API context, see Server API and application runtime. For access rules, see Identity, access, and sharing.

Contract layers

Immich keeps external integration behavior in two contract layers. The API contract describes HTTP operations and data shapes. The plugin contract describes workflow events, method configuration, responses, and approved host access.

ContractMain usersPurpose
OpenAPI documentSDK, CLI, mobile client, other HTTP clientsKeeps requests, responses, permissions, and data types aligned
Hand-maintained SDK surfaceTypeScript tools and plugin packagesAdds client setup and safe HTTP behavior around generated operations
Plugin manifest and SDK typesPlugin authors and the serverDefines methods, configuration, triggers, templates, and host access
Workflow APIWeb UI and external HTTP clientsDiscovers extensions and connects triggers to plugin methods

The server produces the shared OpenAPI document from its HTTP surface. Client generators use that document to create typed client code. Hand-maintained code then adds behavior that depends on the runtime or the needs of a particular client. References: server/…/sync-open-api.ts• L1-23, server/…/index.ts• L48-95, open-api/immich-openapi-specs.json• L1-105, mise.toml• L56-83

API contracts

The OpenAPI document is the public agreement between the Immich server and HTTP clients. It records endpoint paths, request and response schemas, security choices, permissions, lifecycle state, and compatibility history. It also describes plugin discovery and workflow resources, so an external tool can find installed plugins, methods, templates, triggers, workflows, and workflow logs through the same typed boundary. The server version response carries a feature level that expresses supported capability separately from the release version. References: open-api/immich-openapi-specs.json• L74-104, open-api/immich-openapi-specs.json• L10747-11070, open-api/immich-openapi-specs.json• L17687-18179, open-api/immich-openapi-specs.json• L28098-28139

The document also carries the contract for shared access to people data. Clients can inspect access relationships, grant access to people, or remove access through typed operations. These people-access operations are marked Beta in the contract, so clients must treat their shape and support level accordingly. References: open-api/immich-openapi-specs.json• L10081-10264

Generated client contracts

The TypeScript SDK is the main reusable HTTP client for Node and browser-side tools. Its generated part supplies typed operations and models for the API, including plugin discovery and workflow management. Its hand-maintained part supplies the base URL and API key setup, extra headers, asset URL helpers, and clear errors for HTTP or non-JSON responses. References: packages/…/fetch-client.ts• L1-15, packages/…/fetch-client.ts• L2115-2174, packages/…/fetch-client.ts• L3215-3312, packages/…/fetch-client.ts• L6350-6428, packages/…/fetch-client.ts• L7832-7954, packages/…/index.ts• L1-94, packages/…/fetch-errors.ts• L1-43

The mobile client uses the same OpenAPI source but generates Dart code for its own runtime. This shares the server contract without forcing the mobile client to use the TypeScript SDK. API changes therefore need to remain usable by both generated client families. References: open-api/…/generate-dart-sdk.sh• L1-26, open-api/openapitools.json• L1-7, .github/…/check-openapi.yml• L1-65

Contract change checks

Generated clients are downstream products of the OpenAPI document. Pull request checks compare API changes for breaking behavior and check that new required fields remain safe for older mobile clients. The SDK is published as @immich/sdk, while the CLI consumes the generated API surface and must use a current client to build. The server feature level is a required version field, so clients that use it must account for that contract rather than rely only on release version numbers. References: .github/…/check-openapi.yml• L1-65, .github/…/sdk.yml• L1-45, packages/…/package.json• L1-29, packages/…/package.json• L20-59, open-api/immich-openapi-specs.json• L28098-28139

TypeScript SDK

The @immich/sdk package gives external TypeScript code a typed path to Immich resources. A consumer configures one shared client with the server URL and API key, then uses generated operations for resources such as assets, albums, users, plugins, and workflows. References: packages/…/README.md• L1-26, packages/…/index.ts• L7-30, packages/…/fetch-client.ts• L6350-6428, packages/…/fetch-client.ts• L7832-7954

The SDK keeps connection setup separate from ordinary request headers. It also checks that a response marked as JSON is really JSON. This lets an integration distinguish an Immich API error from a wrong URL or a reverse proxy that returned a page instead. References: packages/…/index.ts• L32-81, packages/…/fetch-errors.ts• L3-43

Command-line client

The Immich CLI is a user-facing Node client built on @immich/sdk. It authenticates against a self-hosted server with an API key and provides commands for common server tasks, including asset import. References: packages/…/index.ts• L14-99, packages/…/auth.ts• L14-56, packages/…/utils.ts• L27-100

Asset import flow

The asset command turns local media into server assets. It first scans supported image and video files, then hashes files and asks the server which files are new. It uploads accepted files and can place the results in albums. The command can also watch for later file changes, include sidecar metadata, emit JSON results, or remove local files when the selected operation finishes. References: packages/…/asset.ts• L69-177, packages/…/asset.ts• L179-307, packages/…/asset.ts• L401-454, packages/…/asset.ts• L456-590

The import flow favors safe repeat use. Duplicate checks and uploads retry transient work, while a dry run reports the planned changes without sending uploads or deleting local files. The command also preserves the server's sidecar naming preference and filters watched files by the media types reported by the server. References: packages/…/asset.ts• L179-183, packages/…/asset.ts• L230-279, packages/…/asset.ts• L309-398, packages/…/asset.ts• L444-469, packages/…/asset.spec.ts• L67-126, packages/…/asset.spec.ts• L203-229

The following sequence shows how a local file becomes a server asset or a deliberate duplicate result.

sequenceDiagram
    participant User
    participant CLI
    participant SDK
    participant Server
    User->>CLI: Start import
    CLI->>Server: Authenticate and check upload permission
    CLI->>CLI: Scan and hash supported files
    CLI->>SDK: Check files for duplicates
    SDK->>Server: Send checksums
    Server-->>SDK: Accept or reject each file
    CLI->>Server: Upload accepted files
    Server-->>CLI: Return asset results
    CLI->>Server: Update albums when requested

References: packages/…/asset.ts• L139-161 packages/…/asset.ts• L227-306 packages/…/asset.ts• L350-398 packages/…/asset.spec.ts• L67-126

Plugin ecosystem

Immich plugins are WebAssembly extensions that add workflow methods and optional workflow templates. A plugin presents a manifest and a module. Immich validates the manifest, registers the methods, and makes them available to workflows. References: server/…/plugin-manifest.dto.ts• L50-77, server/…/workflow-execution.service.ts• L225-279, server/…/plugin.table.ts• L13-50

The manifest is the hand-maintained contract for an extension. It names the plugin, describes each method, defines its accepted workflow data and configuration, and declares whether it may call host functions. Templates turn compatible methods into ready-to-use workflow choices. References: server/…/plugin-manifest.dto.ts• L14-48, server/…/plugin-manifest.dto.ts• L50-74

Plugin SDK

The @immich/plugin-sdk package gives plugin authors typed workflow events, configuration values, responses, and host functions. Its wrapper connects exported method names to the WebAssembly boundary. It passes event data into a method and returns workflow decisions, asset changes, continuation data, or configuration updates. References: packages/…/types.ts• L16-72, packages/…/sdk.ts• L55-107

Host functions let a plugin request selected Immich actions without sending raw authenticated requests. The available actions include album work, bulk tag updates, and controlled HTTP requests. Each call runs under the workflow owner's identity, so normal access rules still apply. References: packages/…/host-functions.ts• L18-31, packages/…/host-functions.ts• L46-108, server/…/workflow-execution.service.ts• L169-207

External HTTP access is limited by two checks. The method must declare host access in its manifest. The requested host must also match an allowed host pattern for that method. References: server/…/workflow-execution.service.ts• L35-38, server/…/workflow-execution.service.ts• L85-112, server/…/workflow-execution.service.ts• L126-157

Plugin core

The core plugin is the reference extension for asset workflows. It provides filters for file names, dates, location, EXIF values, tags, type, and time-zone state. It also provides actions for tags, albums, archive state, favorite state, lock state, visibility, and webhooks. References: packages/…/index.ts• L41-231, packages/…/index.ts• L233-270, packages/…/manifest.json• L8-80, packages/…/manifest.json• L80-558

The filters decide whether a workflow continues. The actions return changes or call approved host functions. The webhook method sends the workflow event to a configured URL through the controlled HTTP boundary rather than bypassing the plugin security model. References: packages/…/index.ts• L74-143, packages/…/index.ts• L145-229

Workflow integration

Workflows connect a server trigger to an ordered set of plugin methods. A method key identifies the plugin and method to run. The server checks that each method exists and supports the selected trigger before it accepts the workflow. References: server/…/workflow.controller.ts• L25-66, server/…/workflow.service.ts• L45-80, server/…/workflow.service.ts• L105-124, open-api/immich-openapi-specs.json• L17687-18179

At run time, Immich sends a typed event to the selected plugin method. The method can stop the workflow, pass data onward, request asset changes, or update saved configuration. Methods that need host access run with only the approved server functions available to them. References: packages/…/types.ts• L30-60, server/…/workflow-execution.service.ts• L135-161

The API exposes the workflow lifecycle to external tools. A client can discover supported triggers and plugin methods, create or update an ordered workflow, enable logging, read run results, and obtain a shareable workflow view. The workflow contract also records that PATCH is the migration path for updates before PUT is dropped in a later major version. References: open-api/immich-openapi-specs.json• L10747-11070, open-api/immich-openapi-specs.json• L17687-18179, packages/…/fetch-client.ts• L6350-6428, packages/…/fetch-client.ts• L7832-7954

This diagram shows how an installed extension becomes a workflow result.

flowchart LR
    A[Manifest and WebAssembly module] --> B[Validation and registration]
    B --> C[Workflow method selection]
    C --> D[Trigger event]
    D --> E[Plugin SDK wrapper]
    E --> F{Host function needed?}
    F -- No --> G[Workflow response]
    F -- Yes --> H[Approved Immich or HTTP action]
    H --> G
    G --> I[Next step or asset change]

References: server/…/workflow-execution.service.ts• L55-72 server/…/workflow-execution.service.ts• L225-279 server/…/workflow.service.ts• L105-124 packages/…/sdk.ts• L68-99

External integration boundaries

External tools should use the typed HTTP API or the plugin host boundary. The SDK and CLI are the normal TypeScript paths. Plugins use workflow events for automation and host functions for server actions that need Immich authentication and access checks.

Integration needPreferred boundaryResult
Read or change ordinary Immich resourcesOpenAPI API through @immich/sdkTyped requests and responses
Import media from a local machineImmich CLIPermission-aware upload and duplicate handling
React to asset eventsPlugin workflow methodTyped event and workflow result
Change albums or tags from a pluginPlugin host functionServer-side access checks under the workflow identity
Call an outside service from a pluginManifest-approved HTTP host functionRequest limited by method host rules

The API and plugin boundaries serve different needs. Use the API for a general-purpose external client. Use a plugin when the work belongs inside a workflow and needs event data or controlled server actions. Deployment and end-to-end checks are covered in Deployment and end-to-end validation. Server request behavior is covered in Server API and application runtime, while identity and access rules are covered in Identity, access, and sharing.

Change checklist

When these files or sections are changed, remember to consider these:

  • Changes to server controllers or data types require regeneration of open-api/immich-openapi-specs.json and review of both TypeScript and Dart clients.
  • Changes to an OpenAPI operation or schema require updates to generated consumers, including CLI imports and any external code that uses the old name.
  • New plugin or workflow API fields must stay aligned across the OpenAPI schema, generated SDK types, and the client methods that send or read them.
  • New required API fields need a mobile compatibility patch before older mobile clients can consume the changed shape.
  • Changes to the server version response must keep the required feature level aligned across the OpenAPI schema and generated clients. Clients must not infer supported capability from release version alone.
  • Changes to a plugin method, trigger, workflow data type, or configuration schema must stay aligned across the manifest, exported module, SDK wrapper, and workflow method lookup.
  • Changes to host functions require matching updates to the plugin SDK surface, generated WebAssembly declarations, and server host bindings.
  • Changes to host patterns or permission rules must preserve both the manifest declaration and the server request boundary.
  • Changes to CLI duplicate handling, retry behavior, sidecar rules, or watch batching must preserve the user-visible result of both one-time imports and long-running imports.
  • Changes to workflow update operations must preserve the documented PATCH migration path and the generated client method shape.
  • Changes to people-access operations must preserve their Beta state and permission contract in generated clients.

Important failure modes

TriggerConsequenceGuard
A client uses a reverse proxy or page URL instead of the Immich APIThe SDK cannot decode the non-JSON responseThe SDK checks JSON responses and raises a malformed-response error
A CLI API key lacks upload permissionImport stops before protected work startsThe CLI checks required permissions before scanning and uploading
An OpenAPI operation or schema changes without client regenerationA client may fail to compile or send the wrong request shapeOpenAPI generation and breaking-change checks run before release
A new required API field has no mobile compatibility handlingAn older mobile client may fail to read or send the changed shapeThe mobile compatibility check requires a patch for new required fields
A client treats the release version as the full capability contractIt may use a feature that the server does not supportThe version response exposes a separate required feature level
A plugin or workflow contract changes without SDK regenerationExternal tools may use missing methods or stale data shapesThe OpenAPI document and generated SDK must change together
A plugin manifest or module is invalidThe plugin is not available to workflowsManifest validation and module import checks reject it
A workflow names an unknown or incompatible methodWorkflow creation or update failsThe server resolves each method and checks trigger compatibility
A plugin calls a host function without declaring accessThe call is deniedThe server requires host access in the method contract
A plugin requests a host outside its allowed patternsThe outside request is deniedThe server matches the request host against the method's allowed patterns
A CLI import cannot reach the server after retriesSome files remain unverified or unuploadedThe CLI reports failed queue tasks and does not treat them as successful assets
A client keeps using PUT after the workflow update migrationA future server version can reject the updateThe OpenAPI history directs clients to migrate to PATCH before PUT is removed
A client treats Beta people access as stableA later contract change can break sharing behaviorThe OpenAPI state and history mark these operations as Beta

Key files

FileWhy to read it
open-api/immich-openapi-specs.jsonShared HTTP contract for generated clients and external API users. It also defines plugin, workflow, people-access, and server feature-level contracts
server/…/sync-open-api.tsEntry point for producing the API contract
packages/…/index.tsHand-maintained SDK setup and response behavior
packages/…/fetch-client.tsGenerated TypeScript API operations and models, including plugin and workflow access
packages/…/index.tsCLI command and authentication boundary
packages/…/asset.tsLocal scan, duplicate check, upload, watch, album, and cleanup flow
packages/…/asset.spec.tsBehavior guarantees for retries, duplicate checks, watching, sidecars, and cleanup
packages/…/types.tsShared workflow event and response contract
packages/…/sdk.tsPlugin method wrapper at the WebAssembly boundary
packages/…/host-functions.tsApproved server and HTTP actions available to plugins
server/…/plugin-manifest.dto.tsPlugin manifest contract and validation rules
server/…/workflow-execution.service.tsPlugin loading, execution, and host access boundary
server/…/workflow.service.tsWorkflow method lookup and trigger checks
packages/…/manifest.jsonReference plugin methods and workflow templates
packages/…/index.tsReference asset filters, actions, and webhook behavior