amp guides
amp guides manages guides: in-app tours, modals, banners, and tooltips. Read commands require guides:read; create, update, and archive require guides:write. Publish and schedule guides in Amplitude.
amp guides list
Returns guides in the project. Results use the standard Developer API list envelope with cursor pagination (cursor, limit).
Full-text search (q) and custom sort orders are not supported yet.
amp guides list --project <project_id> --limit 10
| Flag | Type | Required | Description |
|---|---|---|---|
--project | string | Yes | Amplitude project identifier, backed by the canonical app ID. Alias: --project-id. |
--cursor | string | No | Opaque cursor from pagination.next_cursor on the previous response. Numeric offsets are capped by the underlying search index (10,000 results per query). Well-formed pagination stops before that window; requests whose cursor would exceed it return 400 pagination_not_supported. Alias: --next-cursor. |
--limit | integer | No | Number of items to return. Defaults to 50, max 200. |
--platform | string | No | |
--created-after | string | No | |
--created-before | string | No | |
--created-by | string | No | Filter by creator email or login id (exact match). |
--include-archived | boolean | No |
Requires the guides:read scope.
amp guides get
Get guide.
amp guides get --project <project_id> --guide <guide_id> --include-unpublished-changes
| Flag | Type | Required | Description |
|---|---|---|---|
--project | string | Yes | Amplitude project identifier, backed by the canonical app ID. Alias: --project-id. |
--guide | string | Yes | Guide (tour nudge) identifier. Alias: --guide-id. |
--include-unpublished-changes | boolean | No | When true, return the latest draft (unpublished edits) when one exists. Default false returns the live published guide. |
Requires the guides:read scope.
amp guides create
Creates an unpublished draft guide. Publish, schedule, and test instrumentation are not available via API in v1. At most one content variant is accepted on create; the control key is reserved.
amp guides create --project <project_id> --title "Welcome tour"
| Flag | Type | Required | Description |
|---|---|---|---|
--project | string | Yes | Amplitude project identifier, backed by the canonical app ID. Alias: --project-id. |
--idempotency-key | string | No | Generated automatically when omitted. Header acceptance alone does not guarantee retry deduplication. |
--title | string | Yes | |
--description | string | No | |
--platform | string: web, ios, android, react-native, desktop, flutter | No | Target platform. Guides and surveys without an explicit platform are returned as web. |
--priority | integer | No | |
--variants | array | No | JSON array, or a comma-separated list for strings. |
Requires the guides:write scope.
amp guides update
Updates metadata, targeting, and content variants. For published guides, changes apply to a draft until publish in the UI. latest_version is required and must match the current draft, otherwise the update returns 409. The check runs before the write rather than atomically with it, so it reduces but does not fully prevent lost updates from concurrent writers. Publish, schedule, and test instrumentation are not available via API in v1. Status fields on the response are derived read-only. When variants is sent, it must list every existing variant by id with its unchanged variant key; steps within a variant can be added, edited, reordered, or removed. tags is not writable in v1 and returns 400.
amp guides update --project <project_id> --guide <guide_id> --latest-version <version> --title "Welcome tour v2"
| Flag | Type | Required | Description |
|---|---|---|---|
--project | string | Yes | Amplitude project identifier, backed by the canonical app ID. Alias: --project-id. |
--guide | string | Yes | Guide (tour nudge) identifier. Alias: --guide-id. |
--idempotency-key | string | No | Generated automatically when omitted. Header acceptance alone does not guarantee retry deduplication. |
--title | string | No | |
--description | string | No | |
--platform | string: web, ios, android, react-native, desktop, flutter | No | Target platform. Guides and surveys without an explicit platform are returned as web. |
--priority | integer | No | |
--page-target-segments | array | No | Pages where the guide is eligible. Empty means every page. Each item uses camelCase keys. JSON array, or a comma-separated list for strings. |
--temporarily-hide-page-target-segments | array | No | Page rules that are saved but not currently applied. JSON array, or a comma-separated list for strings. |
--hide-if-page-targeting-not-met | boolean | No | |
--trigger-config | object | No | When the guide or survey appears. One trigger, or an array of triggers where any match fires it. Nested keys keep their stored names (selector, event, event_count, delay). Optional filters and sessionPropertyFilters are accepted and passed through. |
--lifecycle | object | No | How often the guide or survey may show again. periodCount is camelCase; the other keys are snake_case. |
--dismissible | boolean | No | |
--snoozable | boolean | No | |
--snoozable-on-all-steps | boolean | No | |
--snooze-duration | object | No | How long a snooze lasts. |
--snooze-label | string | No | |
--template-source | string | No | |
--show-step-counter | boolean | No | |
--step-counter-format | string | No | |
--tags | array | No | JSON array, or a comma-separated list for strings. |
--variants | array | No | JSON array, or a comma-separated list for strings. |
--latest-version | integer | Yes | Expected latest_version from the last GET with include_unpublished_changes=true. |
Requires the guides:write scope.
amp guides archive
Archives an unpublished guide. A guide counts as published while its flag is enabled, unless it's only in test mode without a schedule; archiving a published guide returns 409 with error_code: cannot_archive_published. Unpublish it in Amplitude first. Use dry_run=true to check whether a guide can be archived. An already archived guide returns 404, like GET.
Requires --yes to apply changes, or --dry-run when supported to validate without applying changes.
amp guides archive --project <project_id> --guide <guide_id> --dry-run
| Flag | Type | Required | Description |
|---|---|---|---|
--project | string | Yes | Amplitude project identifier, backed by the canonical app ID. Alias: --project-id. |
--guide | string | Yes | Guide (tour nudge) identifier. Alias: --guide-id. |
--dry-run | boolean | No | Validate request without performing mutation. |
--idempotency-key | string | No | Generated automatically when omitted. Header acceptance alone does not guarantee retry deduplication. |
Requires the guides:write scope.
Was this helpful?
For AI agents: a documentation index is available at /docs/llms.txt. Append .md to any page URL for markdown, or send Accept: text/markdown.