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.
| Contract | Main users | Purpose |
|---|---|---|
| OpenAPI document | SDK, CLI, mobile client, other HTTP clients | Keeps requests, responses, permissions, and data types aligned |
| Hand-maintained SDK surface | TypeScript tools and plugin packages | Adds client setup and safe HTTP behavior around generated operations |
| Plugin manifest and SDK types | Plugin authors and the server | Defines methods, configuration, triggers, templates, and host access |
| Workflow API | Web UI and external HTTP clients | Discovers 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 need | Preferred boundary | Result |
|---|---|---|
| Read or change ordinary Immich resources | OpenAPI API through @immich/sdk | Typed requests and responses |
| Import media from a local machine | Immich CLI | Permission-aware upload and duplicate handling |
| React to asset events | Plugin workflow method | Typed event and workflow result |
| Change albums or tags from a plugin | Plugin host function | Server-side access checks under the workflow identity |
| Call an outside service from a plugin | Manifest-approved HTTP host function | Request 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
| Trigger | Consequence | Guard |
|---|---|---|
| A client uses a reverse proxy or page URL instead of the Immich API | The SDK cannot decode the non-JSON response | The SDK checks JSON responses and raises a malformed-response error |
| A CLI API key lacks upload permission | Import stops before protected work starts | The CLI checks required permissions before scanning and uploading |
| An OpenAPI operation or schema changes without client regeneration | A client may fail to compile or send the wrong request shape | OpenAPI generation and breaking-change checks run before release |
| A new required API field has no mobile compatibility handling | An older mobile client may fail to read or send the changed shape | The mobile compatibility check requires a patch for new required fields |
| A client treats the release version as the full capability contract | It may use a feature that the server does not support | The version response exposes a separate required feature level |
| A plugin or workflow contract changes without SDK regeneration | External tools may use missing methods or stale data shapes | The OpenAPI document and generated SDK must change together |
| A plugin manifest or module is invalid | The plugin is not available to workflows | Manifest validation and module import checks reject it |
| A workflow names an unknown or incompatible method | Workflow creation or update fails | The server resolves each method and checks trigger compatibility |
| A plugin calls a host function without declaring access | The call is denied | The server requires host access in the method contract |
| A plugin requests a host outside its allowed patterns | The outside request is denied | The server matches the request host against the method's allowed patterns |
| A CLI import cannot reach the server after retries | Some files remain unverified or unuploaded | The CLI reports failed queue tasks and does not treat them as successful assets |
| A client keeps using PUT after the workflow update migration | A future server version can reject the update | The OpenAPI history directs clients to migrate to PATCH before PUT is removed |
| A client treats Beta people access as stable | A later contract change can break sharing behavior | The OpenAPI state and history mark these operations as Beta |
Key files
| File | Why to read it |
|---|---|
| open-api/immich-openapi-specs.json | Shared 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.ts | Entry point for producing the API contract |
| packages/…/index.ts | Hand-maintained SDK setup and response behavior |
| packages/…/fetch-client.ts | Generated TypeScript API operations and models, including plugin and workflow access |
| packages/…/index.ts | CLI command and authentication boundary |
| packages/…/asset.ts | Local scan, duplicate check, upload, watch, album, and cleanup flow |
| packages/…/asset.spec.ts | Behavior guarantees for retries, duplicate checks, watching, sidecars, and cleanup |
| packages/…/types.ts | Shared workflow event and response contract |
| packages/…/sdk.ts | Plugin method wrapper at the WebAssembly boundary |
| packages/…/host-functions.ts | Approved server and HTTP actions available to plugins |
| server/…/plugin-manifest.dto.ts | Plugin manifest contract and validation rules |
| server/…/workflow-execution.service.ts | Plugin loading, execution, and host access boundary |
| server/…/workflow.service.ts | Workflow method lookup and trigger checks |
| packages/…/manifest.json | Reference plugin methods and workflow templates |
| packages/…/index.ts | Reference asset filters, actions, and webhook behavior |