--- title: "install" method: POST path: "/v1/app/{appId}" tags: ["App Installation"] --- # install `POST /v1/app/{appId}` Upsert app installation by its ID. ## Path parameters - `appId` string, required ## Request body - object - `version` string — Version of the app to update to - `option_values` OptionsRef[] — Configuration values for the app components - `component_id` string, required — ID of the component these values are for - `options` Option[], required - `key` string, required — Key matching a config_option from the component - `value` union, required — The configured value for this option - string - boolean - number - `_manifest` string[] — Manifest ID used to create/update the entity ## Response `201` App successfully installed. - Installation — Information about the installed app. Has configuration data of the installed version - `app_id` string, required — ID of the app configuration - `installer_org_id` string, required — Unique identifier for the organization the app is installed in - `owner_org_id` string — Organization ID of the app creator - `enabled` boolean, required — Flag to indicate if the app is enabled. Enabled is set to true when required option values are set. - `name` string, required — Name of the app - `option_values` OptionsRef[] — Configuration values for the app components - `component_id` string, required — ID of the component these values are for - `options` Option[], required - `key` string, required — Key matching a config_option from the component - `value` union, required — The configured value for this option - string - boolean - number - `components` BaseComponent[], required — List of component configurations for the installed version - union - object - `id` string, required — Unique identifier for the component - `name` object — Name of the component - `en` string, nullable — English translation - `de` string, required — German translation - `description` object — Description of the component - `en` string, nullable — English translation - `de` string, required — German translation - `options` Options[] — List of options for the app component - `key` string, required — Unique identifier for this configuration option - `label` string — Human-readable label for the configuration option - `required` boolean — Flag to indicate if this option is required - `description` string — Detailed description of what this configuration option does - `value` union — The configured value for this option. Is only present when the component is installed. - string - boolean - number - `type` 'text' | 'number' | 'boolean' | 'secret', required - `surfaces` object - `component_type` 'CUSTOM_JOURNEY_BLOCK', required - `configuration` JourneyBlockConfig, required - `override_dev_mode` OverrideDevMode — Override URL when app is in dev mode - `override_url` string — URL of the web component object in dev mode - `component_url` string, required — URL of the web component object - `component_tag` string, required — Custom element tag for the component - `component_args` JourneyBlockComponentArgs[] — Arguments to pass to the component - union - … - `component_size` number — Size of the bundle in bytes - `component_mapping` object — Define data which is mapped to entity mapping ui blocks - object - `id` string, required — Unique identifier for the component - `name` object — Name of the component - `en` string, nullable — English translation - `de` string, required — German translation - `description` object — Description of the component - `en` string, nullable — English translation - `de` string, required — German translation - `options` Options[] — List of options for the app component - `key` string, required — Unique identifier for this configuration option - `label` string — Human-readable label for the configuration option - `required` boolean — Flag to indicate if this option is required - `description` string — Detailed description of what this configuration option does - `value` union — The configured value for this option. Is only present when the component is installed. - string - boolean - number - `type` 'text' | 'number' | 'boolean' | 'secret', required - `surfaces` object - `component_type` 'PORTAL_EXTENSION', required - `origin` 'END_CUSTOMER_PORTAL' | 'INSTALLER_PORTAL' - `configuration` PortalExtensionConfig, required - `id` string - `hooks` object[] - `id` string - `type` string - `name` TranslatedString - … - `interval` string[] - `auth` PortalAuth - … - `call` object - … - `links` object[] - `id` string - `type` string - `name` TranslatedString - … - `description` TranslatedString - … - `condition` string - `auth` PortalAuth - … - `redirect` object - … - object - `id` string, required — Unique identifier for the component - `name` object — Name of the component - `en` string, nullable — English translation - `de` string, required — German translation - `description` object — Description of the component - `en` string, nullable — English translation - `de` string, required — German translation - `options` Options[] — List of options for the app component - `key` string, required — Unique identifier for this configuration option - `label` string — Human-readable label for the configuration option - `required` boolean — Flag to indicate if this option is required - `description` string — Detailed description of what this configuration option does - `value` union — The configured value for this option. Is only present when the component is installed. - string - boolean - number - `type` 'text' | 'number' | 'boolean' | 'secret', required - `surfaces` object - `flow_action_config` AppBridgeSurfaceConfig - `app_url` string — URL of the uploaded App Bridge App. This is the entrypoint for the app - `zip_url` string — URL of the uploaded zip file containing the app - `override_url` string — URL of the app in dev mode - `component_type` 'CUSTOM_FLOW_ACTION', required - `configuration` CustomFlowConfig, required - `name` string — Name of the custom action - `description` string — Description of the custom action - `type` 'external_integration', required - `external_integration_settings` object - `url` string — URL to call - `headers` object - object - `id` string, required — Unique identifier for the component - `name` object — Name of the component - `en` string, nullable — English translation - `de` string, required — German translation - `description` object — Description of the component - `en` string, nullable — English translation - `de` string, required — German translation - `options` Options[] — List of options for the app component - `key` string, required — Unique identifier for this configuration option - `label` string — Human-readable label for the configuration option - `required` boolean — Flag to indicate if this option is required - `description` string — Detailed description of what this configuration option does - `value` union — The configured value for this option. Is only present when the component is installed. - string - boolean - number - `type` 'text' | 'number' | 'boolean' | 'secret', required - `surfaces` object - `component_type` 'ERP_INFORM_TOOLKIT', required - `configuration` object, required - `type` 'inbound' | 'outbound', required - `installed_version` string, required — Version of the app that is installed - `role` string — The name of the role the app can use to access APIs - `blueprint_ref` BlueprintRef - `manifest_id` string — ID of the blueprint - `job_id` string — ID of the job that created the blueprint - `installation_audit` object — Audit information for the app - `created_at` string — Timestamp of the creation - `created_by` string — User ID of the creator - `updated_at` string — Timestamp of the last update - `updated_by` string — User ID of the last updater - `_manifest` string[] — Manifest ID used to create/update the entity ## Other responses - `404` — App not found. ## Changes - **2025-06-19** `03b93188c6d4` — 1 info - added the new optional request property `_manifest` - **2025-06-18** `d6e3c1e0a11b` — 4 breaking, 1 warning, 6 info - the `option_values/items/options/items/value` request property type/format changed from `string`/`` to `string, boolean, number`/`` - added `#/components/schemas/ErpInformToolkitComponent` to the `components/items/allOf[subschema #2]/` response property `oneOf` list for the response status `201` - the `components/items/allOf[#/components/schemas/BaseComponentCommon]/options/items/value` response's property type/format changed from `string`/`` to `string, boolean, number`/`` for status `201` - the `option_values/items/options/items/value` response's property type/format changed from `string`/`` to `string, boolean, number`/`` for status `201` - …7 more - **2025-05-22** `2ab2aaf08d93` — 1 breaking, 1 warning, 4 info - added `#/components/schemas/CustomFlowActionComponent` to the `components/items/allOf[subschema #2]/` response property `oneOf` list for the response status `201` - added the new `number` enum value to the `components/items/allOf[subschema #2]/oneOf[#/components/schemas/JourneyBlockComponent]/configuration/component_mapping/additionalProperties/` response property for the response status `201` - added the new optional request property `version` - added the optional property `_manifest` to the response with the `201` status - …2 more - …earlier changes not shown [Full history](https://skmtc.dev/epilot/apis/app-api/changes/v1/app/:appId/post.md) --- [API](https://skmtc.dev/epilot/apis/app-api.md) · [All operations](https://skmtc.dev/epilot/apis/app-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/epilot/app-api/revisions/03b93188c6d4/schema)