apps

Install an app

Turns the app on for this account and fires its install lifecycle: the pre_install gate, then the app's own artifact moving to active, then the seeding post_install hook under your bearer — which is how an app's per-account seeds (a bootstrap skill, a default provider) are attributed to the caller rather than to the platform.

Idempotent, and a re-install is the retry. Installing an already-installed app re-fires both hooks and re-merges their metadata, keeping the original created_by and created_at. Every documented seed is idempotent, so this is how an install whose seeds failed is recovered.

Only pre_install can refuse. Once the app is active the install stands: a failing seed hook leaves it installed with no per-account state rather than rolling back, because a rolled-back install leaves nothing to retry from. An app that cannot be reached at all installs with empty metadata for the same reason — a deployment window must not become an onboarding outage.

Requires the account to have been onboarded: an app is an artifact, and an artifact needs the org root workspace that onboarding creates.

post/registry/v1/apps/{app}/install

Request

  • Base URL: https://api.atlan.com (the document declares no server; this is the origin it was published from)
  • URL: https://api.atlan.com/registry/v1/apps/{app}/install
  • Auth: HTTP bearer

Path parameters

appstring required

The app's name, which is the extension's name.

Headers

Content-Encoding'base64' | 'gzip, base64'

Codings applied to the request body, outermost last. Send base64, or gzip, base64 to compress first; the body is decoded before it is read and Content-Type still names the inner media type. Omit for an unencoded body.

Request body

configobject nullable

Install-time configuration, handed verbatim to the app's install hooks and stored nowhere. Not a place for credentials — an app that needs one takes a reference into the secret provider, because this object reaches the hook in cleartext.

Response

Installed, or already was.

access_expires_atstring nullable

Clock deadline for these commercial rights, when bounded.

access_reasonstring nullable

Why can_install and can_use are false, when they are: subscription_required when the plan does not grant the app, or commercial_access_unavailable when billing could not be read and both are refused until it can. Installation and stored data remain intact.

appstring required

The app's name, which is the extension's name.

authorstring nullable

Who publishes this app, as display text.

author_urlstring nullable

Value of the author_url field.

can_installboolean required

Whether the active subscription permits new installation. User permissions also apply.

can_useboolean required

Whether the active subscription permits using an existing installation.

categoriesstring[] required

Always arrays on the wire, never null — a client iterating them should not have to distinguish "none" from "unset".

contract_versioninteger nullable

Value of the contract_version field.

descriptionstring nullable

Human-readable description.

display_namestring required

Human-readable name.

homepage_urlstring nullable

Value of the homepage_url field.

icon_uristring nullable

The app's logo.

install_metadataobject required

Whatever the app's install hooks wrote back about this account.

install_statusstring required

available | installing | active | uninstalling | failed.

installed_atstring required

Value of the installed_at field.

installed_bystring required

Value of the installed_by field.

is_installedboolean required

Whether this account has the app turned on — install_status == "active", and nothing else. The transitional states are not installed: installing has not finished its seed and failed did not.

is_pinnedboolean required

Whether pinned.

licensestring nullable

Value of the license field.

readme_uristring nullable

Value of the readme_uri field.

releasestring nullable

Value of the release field.

repo_urlstring nullable

Value of the repo_url field.

summarystring nullable

Value of the summary field.

support_urlstring nullable

Value of the support_url field.

tagsstring[] required

Value of the tags field.

ui_pathstring nullable

Where the app's browser UI is mounted, relative to the gateway root (/skill/v1/ui/), or absent when it serves none.

updated_atstring required

Value of the updated_at field.

Changes

No recorded changes to this operation across all 1 revision of this API.