UpdateAppPayload

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/vertesiahq/main/json-schema/vertesiahq-update-app-payload-schema.json",
  "title": "UpdateAppPayload",
  "x-generated": "2026-10-22",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/vertesia-openapi.json#/components/schemas/UpdateAppPayload",
  "type": "object",
  "properties": {
    "parameters": {
      "type": "object",
      "propertyNames": {
        "type": "string",
        "pattern": "^[a-z][a-z0-9_]*$"
      },
      "additionalProperties": {
        "$ref": "#/$defs/McpConnectionParameter"
      },
      "description": "Shared MCP installation parameters available to every collection. Collection-local names must not overlap."
    },
    "oauth_scopes": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "oauth_client": {
      "$ref": "#/$defs/AppOAuthClientConfig"
    },
    "name": {
      "type": "string",
      "description": "The name of the app, used as the id in the system. Must be in kebab case (e.g. my-app)."
    },
    "visibility": {
      "type": "string",
      "enum": [
        "public",
        "private",
        "vertesia"
      ],
      "description": "Visibility level of the app:\n- \"public\": visible to all accounts\n- \"private\": visible only to the owning account\n- \"vertesia\": visible only to Vertesia team members (any project)"
    },
    "title": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "publisher": {
      "type": "string"
    },
    "icon": {
      "type": "string",
      "description": "A svg icon for the app."
    },
    "color": {
      "type": "string",
      "description": "A color name to be used as the color of the app card (e.g. blue, red, green, etc.) If not specified a random color will be picked."
    },
    "preview_screenshot": {
      "type": "object",
      "properties": {
        "agent_run_id": {
          "type": "string",
          "description": "Agent run id whose artifact storage holds the screenshot."
        },
        "artifact": {
          "type": "string",
          "description": "Artifact path within that storage, e.g. \"preview-checks/app-preview-<ts>.png\"."
        }
      },
      "required": [
        "agent_run_id",
        "artifact"
      ],
      "additionalProperties": false,
      "description": "Optional preview screenshot for the app-management UI, captured by the builder during a build/QA run. Resolved client-side from the owning agent run's artifact storage, so it carries both the run id and the artifact path."
    },
    "status": {
      "type": "string",
      "enum": [
        "beta",
        "stable",
        "deprecated"
      ]
    },
    "ui": {
      "$ref": "#/$defs/AppUIConfig",
      "description": "The UI configuration of the app. If not specified and the app \"ui\" is in the app capabilities then the ui configuration will be fetched from the endpoint property."
    },
    "tool_collections": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ToolCollectionObject"
      },
      "description": "A list of tool collections endpoints to be used by this app. Prefer using endpoint over tool_collections."
    },
    "oauth_providers": {
      "$ref": "#/$defs/MCPOAuthConfigMap",
      "description": "Named OAuth providers shared across multiple MCP tool collections. Keys must be kebab-case identifiers. Each value is an MCPOAuthConfig blueprint. Collections reference a provider via MCPToolCollectionObject.oauth_provider. One OAuth provider is created per provider at install time; all referencing collections share that app via AppInstallation.provider_bindings."
    },
    "interactions": {
      "type": "string",
      "description": "An URL providing interactions definitions in JSON format. The URL must provide 2 endpoints: 1. GET URL - must return a JSON array with the list of interactions (as AppInteractionRef[]) 2. GET URL/{interaction_name} - must return the full interaction definition for the specified interaction. This feature is for advanced composition of interactions. Prefer using endpoint."
    },
    "settings_schema": {
      "deprecated": true,
      "x-deprecated-message": "Use endpoint to provide settings_schema instead",
      "$ref": "#/$defs/JSONSchema",
      "description": "A JSON chema for the app installation settings.\n\nDeprecated: Use endpoint to provide settings_schema instead"
    },
    "capabilities": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/AppCapabilities"
      },
      "description": "Describe the capabiltities of this app - which kind of contributions it provides."
    },
    "endpoint": {
      "type": "string",
      "description": "The app endpoint URL This URL should return a JSON object describing the contributions provided by the app. The object shape must satisfies AppPackage interface. The endpoint must support GET method and a `scope` parameter to filter which resources are included in the returned AppPackage: The supported scope values are:\n- ui\n- tools\n- interactions\n- types\n- processes\n- templates\n- dashboards\n- settings\n- all (the default if no scope is provided)  You can also use comma-separated values to combine scopes (e.g. \"ui,tools\").\n\nExample:\n- ?scope=ui,tools - returns only the UI configuration"
    },
    "endpoint_overrides": {
      "$ref": "#/$defs/StringValueMap",
      "description": "Optional endpoint overrides keyed by environment name. When resolving the app endpoint, if the current environment name matches a key, the corresponding URL is used instead of the main `endpoint`. Only dev environment names are allowed as keys (starting with \"desktop-\" or \"dev-\")."
    },
    "version": {
      "type": "string",
      "description": "Optional app version string (e.g. \"1.0.0\") — informational."
    },
    "source": {
      "$ref": "#/$defs/AppSourceConfig",
      "description": "Source repository configuration for apps generated and maintained through AppGen. Branches are mutable development lanes; immutable app versions record their exact source commit in AppVersionRecord.source_commit and AppVersionRecord.storage.source_git."
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Free-form tags used for classification and filtering. Platform apps carry `\"system\"` so UIs can skip install/uninstall/manage-permission controls that don't apply to synthetic installations."
    },
    "access_control": {
      "$ref": "#/$defs/AppAccessControl",
      "description": "Access control policy for the app. Defaults to 'all' (ACE-gated everywhere) when undefined. See  {@link  AppAccessControl }  for semantics. May be overridden on the AppInstallation."
    },
    "expected_edit_revision": {
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991,
      "description": "Edit revision returned by the last read. Stale revisions are rejected with HTTP 409. Omit for legacy last-write-wins behavior."
    }
  },
  "required": [
    "name",
    "visibility",
    "title",
    "description",
    "publisher",
    "status"
  ],
  "additionalProperties": false,
  "$defs": {
    "AppAccessControl": {
      "type": "string",
      "enum": [
        "all",
        "ui",
        "none"
      ],
      "description": "Access control policy for an app installation. Declares which access surfaces are gated by per-user ACEs.\n\n- 'all' (default): every surface (UI portal, tool/endpoint use, contributions) requires   an explicit app_member ACE — the historical behavior.\n- 'ui': UI portal visibility requires an ACE, but tool/endpoint use and contributions   are open to anyone in the project.\n- 'none': fully open within the project — no ACE required for any surface.\n\nDeclared on the manifest as the app's default. May be overridden per-installation."
    },
    "AppAvailableIn": {
      "type": "string",
      "enum": [
        "app_portal",
        "composite_app"
      ]
    },
    "AppCapabilities": {
      "type": "string",
      "enum": [
        "ui",
        "tools",
        "interactions",
        "types",
        "processes",
        "views",
        "templates",
        "dashboards"
      ]
    },
    "AppGitSourceConfig": {
      "type": "object",
      "properties": {
        "provider": {
          "$ref": "#/$defs/AppGitSourceProvider",
          "description": "Repository provider. Missing values are treated as `vertesia` for apps created before provider support."
        },
        "url": {
          "type": "string"
        },
        "installation_id": {
          "type": "string",
          "description": "Verified GitHub App installation id. Required when provider is `github`."
        },
        "repository": {
          "type": "string",
          "description": "GitHub repository in `owner/name` form. Required when provider is `github`."
        },
        "default_branch": {
          "type": "string"
        },
        "production_branch": {
          "type": "string"
        },
        "development_branch": {
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "AppGitSourceProvider": {
      "type": "string",
      "enum": [
        "vertesia",
        "github"
      ]
    },
    "AppOAuthClientConfig": {
      "type": "object",
      "properties": {
        "redirect_uris": {
          "minItems": 1,
          "type": "array",
          "items": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "required": [
        "redirect_uris"
      ],
      "additionalProperties": false,
      "description": "Standalone public PKCE OAuth. Installation automatically provisions an app client with these exact callback URLs."
    },
    "AppSourceConfig": {
      "type": "object",
      "properties": {
        "kind": {
          "type": "string",
          "const": "git"
        },
        "git": {
          "$ref": "#/$defs/AppGitSourceConfig"
        }
      },
      "required": [
        "kind"
      ],
      "additionalProperties": false
    },
    "AppUIConfig": {
      "type": "object",
      "properties": {
        "src": {
          "type": "string",
          "description": "The source URL of the app. The src can be a template which contain a variable named `buildId` which will be replaced with the current build id. For example: `/plugins/vertesia-review-center-${buildId}`"
        },
        "isolation": {
          "type": "string",
          "enum": [
            "shadow",
            "css",
            "iframe"
          ],
          "description": "The isolation strategy. If not specified it defaults to shadow.\n- shadow - use Shadow DOM to fully isolate the plugin from the host.\n- css - inject the plugin's styles (minus the preflight) into the host document; lighter but styles may conflict with the host.\n- iframe - load a standalone application in a sandboxed iframe so it owns its JavaScript and dependency graph."
        },
        "css_rebuild": {
          "type": "boolean",
          "description": "When true the host modifies the app's css at load time to attempt to fix broken or missing styles. Only takes effect in css isolation mode. Defaults to false."
        },
        "navigation": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AppUINavItem"
          },
          "description": "Navigation items for the app's sidebar UI. Only applicable for apps with UI capability in shell contexts (ie. CompositeApp shell)."
        },
        "available_in": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AppAvailableIn"
          },
          "description": "Where this app's UI can be displayed.\n- 'app_portal': Available in the main app portal (standalone)\n- 'composite_app': Available within a CompositeApp shell Defaults to ['app_portal', 'composite_app'] for new apps."
        }
      },
      "required": [
        "src"
      ],
      "additionalProperties": false
    },
    "AppUINavItem": {
      "type": "object",
      "properties": {
        "label": {
          "type": "string",
          "description": "Display label"
        },
        "icon": {
          "type": "string",
          "description": "Lucide icon name or SVG content string"
        },
        "route": {
          "type": "string",
          "description": "Route path relative to app base"
        },
        "description": {
          "type": "string",
          "description": "Optional description shown on dashboard cards and other summary views"
        },
        "children": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AppUINavItem"
          },
          "description": "Nested sub-items displayed within this item's collapsible section"
        },
        "topLevel": {
          "type": "boolean",
          "description": "When true, this item appears as an independent entry in the sidebar (outside its parent app group)"
        },
        "preferredSection": {
          "type": "string",
          "enum": [
            "default",
            "footer",
            "settings"
          ],
          "description": "Which sidebar section this item should be placed in when first added.\n- \"default\" or unset: normal behavior (child of its app group)\n- \"footer\": placed in the footer section\n- \"settings\": placed in the settings section"
        }
      },
      "required": [
        "label",
        "icon",
        "route"
      ],
      "additionalProperties": false,
      "description": "Additional navigation item for an app's UI configuration. Used in AppUIConfig.navigation to define sidebar navigation entries in CompositeApp shell contexts. Icon values are Lucide icon component names or SVG content strings."
    },
    "JSONSchema": {
      "type": "object",
      "properties": {
        "type": {},
        "description": {
          "type": "string"
        },
        "properties": {
          "$ref": "#/$defs/JSONSchemaProperties"
        },
        "items": {
          "$ref": "#/$defs/JSONSchema"
        },
        "format": {
          "type": "string"
        },
        "editor": {},
        "default": {},
        "additionalProperties": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "$ref": "#/$defs/JSONSchema"
            }
          ]
        },
        "required": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "JSONSchemaProperties": {
      "type": "object",
      "additionalProperties": {
        "$ref": "#/$defs/JSONSchema"
      }
    },
    "MCPApiKeyConfig": {
      "type": "object",
      "properties": {
        "required_at_install": {
          "type": "boolean",
          "description": "When true, the installer must supply the key in the install dialog. Use this for a manifest published to projects that each hold their own key. Leave unset when the key was already stored by whoever registered the server."
        },
        "instructions": {
          "type": "string",
          "description": "Shown in the install dialog above the key field — typically where to generate the key on the remote service."
        }
      },
      "additionalProperties": false,
      "description": "Install-time provisioning blueprint for an `auth: 'api_key'` MCP collection. Declares whether the installer is prompted for the key. Never holds the key itself — manifests are shareable documents."
    },
    "MCPOAuthConfig": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Name for the OAuth provider to create at install time. Defaults to the collection id converted to kebab-case if not specified."
        },
        "display_name": {
          "type": "string",
          "description": "Human-readable display name for the created OAuth provider."
        },
        "grant_type": {
          "type": "string",
          "enum": [
            "authorization_code",
            "client_credentials"
          ]
        },
        "authorization_endpoint": {
          "type": "string"
        },
        "token_endpoint": {
          "type": "string"
        },
        "revocation_endpoint": {
          "type": "string"
        },
        "client_id": {
          "type": "string",
          "description": "Pre-configured client_id. Omit if the installer must supply it (include 'client_id' in required_at_install)."
        },
        "use_pkce": {
          "type": "boolean"
        },
        "default_scopes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "required_at_install": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "client_id",
              "client_secret",
              "scopes"
            ]
          },
          "description": "Parameters the installer must provide at install time. These are shown as form fields in composable-ui before the install completes.\n- 'client_id': user supplies the OAuth client ID\n- 'client_secret': user supplies the OAuth client secret"
        }
      },
      "additionalProperties": false,
      "description": "Install-time OAuth provisioning blueprint for an MCP collection. Defines how to auto-create an OAuth provider when the app is installed. Does NOT affect runtime behaviour — the runtime uses oauth_bindings on AppInstallation."
    },
    "MCPOAuthConfigMap": {
      "type": "object",
      "additionalProperties": {
        "$ref": "#/$defs/MCPOAuthConfig"
      }
    },
    "MCPToolCollectionObject": {
      "type": "object",
      "properties": {
        "url": {
          "type": "string",
          "description": "The URL endpoint for the tool collection"
        },
        "auth": {
          "$ref": "#/$defs/ToolCollectionAuthType",
          "description": "Optional authentication type required for this tool collection"
        },
        "type": {
          "type": "string",
          "const": "mcp"
        },
        "parameters": {
          "type": "object",
          "propertyNames": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9_]*$"
          },
          "additionalProperties": {
            "$ref": "#/$defs/McpConnectionParameter"
          }
        },
        "headers": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "description": "HTTP header templates. Reference declared installation parameters with {{name}}. Never embed secrets."
        },
        "id": {
          "type": "string",
          "description": "Stable identifier for this collection. Used to key oauth_bindings on AppInstallation — protects against collection renames. Required for new manifests."
        },
        "name": {
          "type": "string",
          "description": "Name for the tool collection. Human-readable label for the collection. Used in UI."
        },
        "description": {
          "type": "string",
          "description": "Description for the tool collection. Helps users understand what tools this collection provides."
        },
        "namespace": {
          "type": "string",
          "description": "Prefix to use for tool names from this collection. Provides clean, readable tool names (e.g., \"jira\" instead of \"https://mcp.atlassian.com/v1/mcp\")"
        },
        "oauth_app": {
          "type": "string",
          "description": "Reference to an OAuth provider name for this collection (legacy / manual path). When set, uses the OAuth provider's config (endpoints, client_id, client_secret) instead of MCP dynamic client registration or random fallback. The referenced OAuth provider must exist in the same project."
        },
        "oauth_config": {
          "$ref": "#/$defs/MCPOAuthConfig",
          "description": "Install-time OAuth provisioning blueprint. When present, the platform auto-creates an OAuth provider at install time using these values merged with any user-supplied required_at_install params. The created app is recorded in AppInstallation.oauth_bindings. Mutually exclusive with oauth_provider."
        },
        "api_key_config": {
          "$ref": "#/$defs/MCPApiKeyConfig",
          "description": "Install-time provisioning blueprint for auth: 'api_key' collections. Only meaningful alongside auth: 'api_key'; ignored otherwise."
        },
        "oauth_provider": {
          "type": "string",
          "description": "Reference to a key in AppManifestData.oauth_providers. When set, this collection shares the named provider's OAuth provider configuration. Mutually exclusive with oauth_config and oauth_app. Requires auth: \"oauth\" to be set."
        },
        "oauth_scopes": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Additional OAuth scopes for this collection when using a shared oauth_provider. These are merged (union) with the provider's default_scopes at install time. Only valid when oauth_provider is set."
        }
      },
      "required": [
        "url",
        "type",
        "id",
        "name",
        "description",
        "namespace"
      ],
      "additionalProperties": false,
      "description": "MCP tool collection configuration (requires name, description, and namespace)"
    },
    "McpConnectionParameter": {
      "anyOf": [
        {
          "$ref": "#/$defs/McpPublicParameter"
        },
        {
          "$ref": "#/$defs/McpSecretParameter"
        }
      ]
    },
    "McpPublicParameter": {
      "type": "object",
      "properties": {
        "title": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "required": {
          "type": "boolean"
        },
        "type": {
          "type": "string",
          "const": "string"
        },
        "default": {
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "McpSecretParameter": {
      "type": "object",
      "properties": {
        "title": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "required": {
          "type": "boolean"
        },
        "type": {
          "type": "string",
          "const": "secret"
        }
      },
      "required": [
        "type"
      ],
      "additionalProperties": false
    },
    "StringValueMap": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      }
    },
    "ToolCollectionAuthType": {
      "type": "string",
      "enum": [
        "none",
        "oauth",
        "api_key",
        "other"
      ],
      "description": "Authentication type for tool collections.\n- 'none': connect directly without credentials for MCP collections; does not disable authentication for Vertesia SDK collections\n- 'oauth': the runtime resolves a per-user or per-project OAuth access token\n- 'api_key': a static key held in the project's secret store is sent as the RFC 6750 bearer token (`Authorization: Bearer <key>`)\n- 'other' or omitted: use the legacy provider connection-details flow for MCP collections"
    },
    "ToolCollectionObject": {
      "oneOf": [
        {
          "$ref": "#/$defs/MCPToolCollectionObject"
        },
        {
          "$ref": "#/$defs/VertesiaSDKToolCollectionObject"
        }
      ],
      "type": "object",
      "required": [
        "type"
      ]
    },
    "VertesiaSDKToolCollectionObject": {
      "type": "object",
      "properties": {
        "url": {
          "type": "string",
          "description": "The URL endpoint for the tool collection"
        },
        "auth": {
          "$ref": "#/$defs/ToolCollectionAuthType",
          "description": "Optional authentication type required for this tool collection"
        },
        "type": {
          "type": "string",
          "const": "vertesia_sdk"
        },
        "namespace": {
          "type": "string",
          "description": "Optional namespace to use for tool names from this collection. If not provided, the tool server default will be used."
        },
        "name": {
          "type": "string",
          "description": "Optional name for the tool collection. If not provided, the tool server default will be used."
        },
        "description": {
          "type": "string",
          "description": "Optional description for the tool collection. If not provided, the tool server default will be used."
        }
      },
      "required": [
        "url",
        "type"
      ],
      "additionalProperties": false,
      "description": "Vertesia SDK tool collection configuration"
    }
  }
}