Skip to content

Create webclip for a tenant
Stable

Request

⚠️ iOS/iPadOS only. Webclips are home screen shortcuts for iOS and iPadOS managed devices.

Creates a new webclip in the tenant library, making it available for deployment to iOS/iPadOS managed devices via blueprint or install operation.

About Create Webclip

A webclip is a home screen bookmark that opens a specified URL in a browser or within a target app, appearing as an app icon on the device. In Esper, webclips are managed as a distinct app type (WEBCLIP) within the iOS app system. The request uses multipart/form-data and requires label, esper_name, url, target_bundle_id, target_bundle_name, is_full_screen, and is_removable. An optional icon binary can be uploaded to set a custom home screen icon. The target_bundle_id and target_bundle_name identify the iOS app that will handle the URL (e.g., Safari). A 409 response indicates a webclip with a conflicting identifier already exists.

Key Fields

label (required) — Display name shown on the device home screen

esper_name (required) — Internal name for the webclip in Esper (used for lookup and management)

url (required) — The URL the webclip opens

target_bundle_id (required) — Bundle ID of the app that handles the URL (e.g., com.apple.mobilesafari)

target_bundle_name (required) — Display name of the target bundle (e.g., Safari)

is_full_screen (required) — Whether the webclip opens in full-screen mode

is_removable (required) — Whether the user can remove the webclip from the home screen

icon (optional) — Custom icon binary for the home screen shortcut

Common Use Cases

Creating a home screen shortcut to an internal web app or portal for field devices

Adding a branded webclip with a custom icon that opens in full-screen kiosk-style mode

Deploying a managed browser link that users cannot remove from the home screen

Best Practices

Set is_removable=false for compliance-critical or kiosk-mode webclips that should not be user-removable

Use a descriptive esper_name that distinguishes webclips with similar labels — it is the primary lookup identifier in Esper

After creation, capture the returned id (webclip UUID) for blueprint configuration or install operations

Workflow

Prepare the webclip details — URL, target bundle, label, and icon if needed

Submit the multipart/form-data POST with all required fields

Capture the returned webclip id for use in blueprint or operation configuration

Security
apps_management_apiKey
Bodymultipart/form-datarequired
iconstring, (binary)

Icon of the webclip

labelstringrequired

Label of the web clip which is displayed on device

Example:"Example Label"
esper_namestringrequired

Name of the webclip in Esper

Example:"Example Name"
urlstringrequired

URL for the webclip

Example:"https://example.com"
target_bundle_idstringrequired

Target bundle ID for the webclip

Example:"com.example.bundle"
target_bundle_namestringrequired

Target bundle name for the webclip

Example:"Example Bundle"
is_full_screenbooleanrequired

Indicates if the webclip is full screen

Example:true
is_removablebooleanrequired

Indicates if the webclip is removable

Example:false
cURL
curl -i -X POST \
  https://api.esper.io/_mock/openapi/v2/webclips \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: multipart/form-data' \
  -F icon=string \
  -F 'label=Example Label' \
  -F 'esper_name=Example Name' \
  -F url=https://example.com \
  -F target_bundle_id=com.example.bundle \
  -F 'target_bundle_name=Example Bundle' \
  -F is_full_screen=true \
  -F is_removable=false

Responses

Success

Bodyapplication/json
contentobject(apps_management_Webclip)
Response
{
  "content": {
    "id": "09811f63-e2ca-4625-97c1-081145195d67",
    "tenant_id": "7d5fd1bf-bdf9-490b-9e32-203756a61235",
    "label": "Google",
    "url": "https://www.google.com/",
    "icon_url": null,
    "target_bundle_name": "Esper",
    "target_bundle_id": "com.esper.io",
    "is_full_screen": false,
    "is_removable": true,
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "created_by": "string",
    "updated_by": "string"
  }
}