← All action domains

Apps

31 operations. Call each with POST https://app.chirply.io/api/v1/actions/<name> and a bearer token; the response is { "data": { "action", "summary", "result" } }. A read badge means the operation changes nothing; write requires the credential’s write scope.

Update app

apps.apply_updatewriteconfirmadmin only

Move one installed Marketplace app to its newest published version. For hosted or external apps this immediately changes the app UI and declared event subscriptions running in the account; native apps acknowledge the version of their already-deployed feature. Existing permissions and access token remain unchanged.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
install_idstring (uuid)requiredThe installed app to update to its newest published version.

Example

curl -X POST https://app.chirply.io/api/v1/actions/apps.apply_update \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "install_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool apps_apply_update at https://app.chirply.io/api/mcp, same bearer token, same input.

Pay now

apps.complete_purchasewriteconfirmadmin only

Submit payment for a paid app prepared with apps.start_purchase. On the first call, confirmation_token must come from the buyer's completed Stripe Payment Element; only then does this create and confirm a REAL-MONEY one-time charge or monthly subscription on the developer's Stripe account. If customer authentication is required, call again without the token after Stripe.js completes it. Installs the app only after Stripe verifies payment.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
order_idstring (uuid)requiredThe pending order id from apps.start_purchase.
confirmation_tokenstringoptionalStripe ConfirmationToken from the buyer's submitted Payment Element. Required for the first payment attempt; omit only when rechecking after customer authentication.

Example

curl -X POST https://app.chirply.io/api/v1/actions/apps.complete_purchase \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool apps_complete_purchase at https://app.chirply.io/api/mcp, same bearer token, same input.

Confirm agency checkout

apps.confirm_reseller_checkoutwriteadmin only

After paying on an agency's Stripe Checkout page (from apps.start_reseller_checkout), confirm that payment with the agency's Stripe and switch the app on in THIS account now, instead of waiting for the agency's Stripe webhook. Charges nothing and is safe to repeat — a payment already confirmed changes nothing, and a checkout that was not for this account, not paid, or taken in test mode is refused.

Parameters

FieldTypeRequiredDescription
session_idstringrequiredThe Stripe Checkout Session id the buyer came back with (the `reseller_checkout` value on the return URL).

Example

curl -X POST https://app.chirply.io/api/v1/actions/apps.confirm_reseller_checkout \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool apps_confirm_reseller_checkout at https://app.chirply.io/api/mcp, same bearer token, same input.

Create an app

apps.createwriteadmin only

Create a new app in this agency's developer account, as a private draft. Doesn't publish or list it — that happens later via apps.submit_for_review and platform review. Requires an agency (white-label or reseller) plan. Both hosting modes are live: 'external' loads your own HTTPS URL in a sandboxed iframe, 'hosted' serves a self-contained HTML document you publish through apps.publish_version. Paid apps are live too — apps.start_purchase and apps.complete_purchase take real money from buyers — so set pricing_kind, price_cents and currency to what you actually intend to charge.

Parameters

FieldTypeRequiredDescription
slugstringrequiredGlobally-unique URL-safe id, e.g. 'acme-dialer'. Permanent once set.
namestringrequiredDisplay name shown on the marketplace card.
taglinestringoptionalOne-line pitch for the card.
descriptionstringoptionalFull description for the listing page.
categorystringoptionalMarketplace category, e.g. 'Telephony'.
icon_urlstring (uri)optionalHTTPS URL of the app's square icon (upload via POST /api/apps/images).
screenshotsarray of (string (uri))optionalHTTPS URLs of marketplace screenshots (upload via POST /api/apps/images). Default: []
hosting"external" | "hosted"optional'external' = you host the app UI yourself and register its HTTPS URL; 'hosted' = the app is a single self-contained HTML document Chirply serves in a sandboxed iframe (publish it with apps.publish_version). Default: "external"
external_base_urlstring (uri)optionalFor 'external' hosting: the HTTPS URL the app UI is loaded from. Every page/widget/card path is resolved against it, so changing it repoints the app's whole UI for everyone who has it installed.
requested_scopesstring[]optionalThe most an install may ever grant this app, e.g. ['contacts:read','tasks:write']. Outward-facing actions also need a '<area>:confirm' scope. Default: []
pricing_kind"free" | "one_time" | "subscription"optionalHow the app is sold — free, one-time, or a recurring subscription. Buyers are charged for real; see apps.start_purchase / apps.complete_purchase. Default: "free"
price_centsintegeroptionalPrice in integer cents (2900 = $29.00). Real money, charged to the buyer. Default: 0
currencystringoptionalISO currency code, lowercase, e.g. 'usd'. Default: "usd"
homepage_urlstring (uri)optionalYour app's marketing/support homepage.
support_emailstring (email)optionalWhere installers can reach you.

Example

curl -X POST https://app.chirply.io/api/v1/actions/apps.create \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "example",
    "name": "Example"
  }'
Test with your API key

Over MCP the same operation is the tool apps_create at https://app.chirply.io/api/mcp, same bearer token, same input.

How to build an app

apps.dev_guideread

Read this FIRST. Returns the complete guide to building and publishing a marketplace app with your own AI agent: the hosted vs external model, the create → publish_version → submit_for_review → (admin review) → install flow, the manifest (pages/widgets/cards), the App SDK (chirply.call / chirply.data / chirply.context), the scope grammar, and a minimal worked hosted app. After reading it, use apps.create, apps.publish_version, and apps.submit_for_review.

Parameters

No parameters — POST an empty body.

Example

curl -X POST https://app.chirply.io/api/v1/actions/apps.dev_guide \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{}'
Test with your API key

Over MCP the same operation is the tool apps_dev_guide at https://app.chirply.io/api/mcp, same bearer token, same input.

Connect Stripe for payouts

apps.developer_connectwriteadmin only

Start (or resume) Stripe Connect onboarding so your agency gets PAID for paid app installs. Returns a Stripe-hosted onboarding URL — open it, finish the steps, come back. Money from paid installs settles to this connected account (you're the merchant of record), minus the marketplace fee. Required before you can actually charge for an app.

Parameters

No parameters — POST an empty body.

Example

curl -X POST https://app.chirply.io/api/v1/actions/apps.developer_connect \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{}'
Test with your API key

Over MCP the same operation is the tool apps_developer_connect at https://app.chirply.io/api/mcp, same bearer token, same input.

Payout account status

apps.developer_connect_statusreadadmin only

Check your agency's Stripe Connect payout account for paid app installs — whether it's connected, can accept charges, and can receive payouts.

Parameters

No parameters — POST an empty body.

Example

curl -X POST https://app.chirply.io/api/v1/actions/apps.developer_connect_status \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{}'
Test with your API key

Over MCP the same operation is the tool apps_developer_connect_status at https://app.chirply.io/api/mcp, same bearer token, same input.

Check app ownership

apps.entitlementreadadmin only

Check what this account has PAID for on one app, which is a different question from whether it is currently installed. Returns how it was bought (paid once, monthly, or yearly), whether the account may install it again without paying, when a subscription's paid-up period ends, and whether that subscription is already cancelling. Reads only — spends no money and changes no install. Use it before apps.install on a paid app: an account that already owns one reinstalls for free, so a purchase is not always needed.

Parameters

FieldTypeRequiredDescription
app_idstring (uuid)optionalThe app to check, by id. Give this or slug.
slugstringoptionalThe app to check, by marketplace slug. Give this or app_id.

Example

curl -X POST https://app.chirply.io/api/v1/actions/apps.entitlement \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
    "slug": "example"
  }'
Test with your API key

Over MCP the same operation is the tool apps_entitlement at https://app.chirply.io/api/mcp, same bearer token, same input.

Open an app

apps.getreadadmin only

Fetch one of this agency's apps by id, with all of its fields.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe app's id.

Example

curl -X POST https://app.chirply.io/api/v1/actions/apps.get \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool apps_get at https://app.chirply.io/api/mcp, same bearer token, same input.

View a marketplace listing

apps.get_listingread

Fetch one marketplace app's public listing detail by slug or id: its full description, screenshots, icon, pricing, category, requested scopes, developer name, and how many accounts have it installed. Returns publicly-listed apps, plus your own agency's apps before they're listed. This is the read behind the app's detail page. In a client account whose agency resells the app, the pricing is the AGENCY's and `agency_offer` says who sells it, at what price, whether it can be bought yet (the agency has connected its Stripe) and whether this account already owns it.

Parameters

FieldTypeRequiredDescription
slugstringoptionalThe app's slug, e.g. 'acme-dialer'.
idstring (uuid)optionalThe app's id (use instead of slug).

Example

curl -X POST https://app.chirply.io/api/v1/actions/apps.get_listing \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "example",
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool apps_get_listing at https://app.chirply.io/api/mcp, same bearer token, same input.

Install an app

apps.installwriteconfirmadmin only

Install an app into THIS account and issue it an access token with the scopes you grant. This gives third-party code ongoing API access to the account's data within those scopes — the token is shown once and can't be retrieved again. IT ALSO STARTS SENDING DATA OUT: if the app's manifest subscribes to events and you grant 'events:read', the install provisions those event subscriptions and returns a `webhook_secret`, after which this account POSTs the subscribed events (new contacts, inbound messages, won deals, paid invoices…) to the app developer's own server as they happen, until someone uninstalls. Grant the least it needs, and know where the data is going. Re-installing rotates the existing install.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
app_idstring (uuid)optionalThe app to install (by id).
slugstringoptionalThe app to install (by slug), if id is not given.
grant_scopesstring[]requiredScopes to grant this install — must be within the app's requested_scopes, e.g. ['contacts:read']. Grant the least it needs.
configmap of string → objectoptionalNon-secret per-install settings the app reads back. Default: {}
instance_namestringoptionalName for this distinct install.

Example

curl -X POST https://app.chirply.io/api/v1/actions/apps.install \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_scopes": [
      "example"
    ]
  }'
Test with your API key

Over MCP the same operation is the tool apps_install at https://app.chirply.io/api/mcp, same bearer token, same input.

Install in client accounts

apps.install_for_clientwriteconfirmadmin only

From an AGENCY account, install one of the agency's OWN apps — hosted or external, private, unlisted or listed, reviewed or not — into chosen client accounts directly under it, with the scopes you grant and an optional name per account. It works whatever those client accounts' App Marketplace setting is, and their storefront stays exactly as it was: nothing about the marketplace is shown to or switched on for the client. Each install gives the agency's app code ongoing access to THAT client account's data within the granted scopes and adds the app's pages, dashboard widgets and contact cards there for the client's whole team. For an external app that subscribes to events and is granted 'events:read', it also starts POSTing that account's events (new contacts, inbound messages, won deals, paid invoices…) to the app's own server until it is uninstalled. No purchase runs and nobody is charged: the agency is installing software it owns, so a paid app installs free and creates no order. An account that already has the app is RE-installed — its scopes and name are replaced, it moves to the newest published version, and it gets a new access token, so the old one stops working at once. Every install is recorded in that client account's access log. Gates: the caller is an owner or admin of the agency; the app belongs to the agency (built-in platform apps and suspended apps are refused) and has a published version; every grant is within the app's requested_scopes; every account is an active client account of this agency, and one that requires approval before its agency acts inside it needs an open access window for the acting person. Each account is handled on its own, so a refused account does not stop the others — read `failed` and each result's `error`. Up to 50 accounts per call. Access tokens and webhook secrets in the results are shown once.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
app_idstring (uuid)requiredThe agency's own app to install (apps.list shows them).
accountsobject[]requiredThe client accounts to install into, each with an optional name and scope override. 1 to 50 per call; a repeated account is installed once.
accounts[].account_idstring (uuid)requiredA client account directly under this agency (accounts.list or apps.list_client_installs shows them).
accounts[].instance_namestringoptionalWhat to call this install in that account; it is shown in front of each of the app's page names in that account's navigation, e.g. 'Planning'. Leave out to use the app's own page names.
accounts[].grant_scopesstring[]optionalScopes for THIS account only, replacing the top-level grant_scopes for it. Must be within the app's requested_scopes.
grant_scopesstring[]requiredScopes to grant in every listed account that does not override them. Each must be within the app's requested_scopes, e.g. ['contacts:read']. Grant the least it needs; [] grants no data access.
configmap of string → objectoptionalNon-secret per-install settings the app reads back, applied to every listed account. Default: {}

Example

curl -X POST https://app.chirply.io/api/v1/actions/apps.install_for_client \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
    "accounts": [
      {
        "account_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
      }
    ],
    "grant_scopes": [
      "example"
    ]
  }'
Test with your API key

Over MCP the same operation is the tool apps_install_for_client at https://app.chirply.io/api/mcp, same bearer token, same input.

Install a built-in app

apps.install_nativewriteadmin only

Turn ON one of the platform's built-in (native) first-party apps for this account: Browser Agent ('browser-agent'), Directories ('directories'), Domain Leads ('domain-leads'), Desk Phones ('desk-phones'), Business Cards ('business-cards'), Martial Arts Gym ('martial-arts-gym'), GoHighLevel ('gohighlevel'), Quotes & Proposals ('proposals'), Project Preview ('project-preview'), Restaurant ('restaurant'), Shopify Commerce ('shopify'), Klaviyo ('klaviyo'), Loyalty Cards ('loyalty-cards'), Video Meetings ('video-meetings'), Webinars ('webinars') — the same list apps.list_directory marks as native, and the same Install button on the Apps screen. A native app is a feature shipped inside the product, so this issues no token, grants no scopes, and sends no data to any third party; it simply enables that feature's screens and, for integration apps like GoHighLevel and Klaviyo, unlocks their capability domains (which refuse with app_required until the app is installed). PAID native apps are NOT granted by this: unless the account already owns the app (check apps.entitlement), the install is refused with payment_required and the purchase must go through apps.start_purchase / apps.complete_purchase — exactly the same gate the Install button enforces, so this is never a way to get an app the account hasn't bought. Reinstalling an owned app is free and reactivates every licence the account holds.

Parameters

FieldTypeRequiredDescription
slugstringrequiredThe native app's slug, e.g. 'restaurant', 'klaviyo', 'gohighlevel'. The valid slugs are listed in this capability's description and marked native in apps.list_directory.

Example

curl -X POST https://app.chirply.io/api/v1/actions/apps.install_native \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "example"
  }'
Test with your API key

Over MCP the same operation is the tool apps_install_native at https://app.chirply.io/api/mcp, same bearer token, same input.

List my apps

apps.listreadadmin only

List the apps this agency owns (drafts and published), newest first.

Parameters

FieldTypeRequiredDescription
limitintegeroptionalMax rows to return (1–100). Default: 25
offsetintegeroptionalRows to skip. Default: 0
status"draft" | "in_review" | "approved" | "listed" | "suspended"optionalOnly apps in this review status.
querystringoptionalText to match in name or slug.

Example

curl -X POST https://app.chirply.io/api/v1/actions/apps.list \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 25,
    "offset": 0
  }'
Test with your API key

Over MCP the same operation is the tool apps_list at https://app.chirply.io/api/mcp, same bearer token, same input.

View client account installs

apps.list_client_installsreadadmin only

For an app your AGENCY owns, list every client account directly under this agency and whether the app is installed there: each install's status, the version it runs, whether that is the newest published version, its granted scopes and its name. Also says which client accounts require approval before the agency acts inside them. Use it before apps.install_for_client or apps.update_client_installs. Read-only; changes nothing and is not recorded in the client accounts' access logs.

Parameters

FieldTypeRequiredDescription
app_idstring (uuid)requiredThe agency's own app (apps.list shows them).

Example

curl -X POST https://app.chirply.io/api/v1/actions/apps.list_client_installs \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool apps_list_client_installs at https://app.chirply.io/api/mcp, same bearer token, same input.

Browse the app marketplace

apps.list_directoryread

Browse apps that can be installed into this account — everything listed publicly, plus this agency's own apps (so you can install one before it's listed). Each app includes its cumulative download count across accounts, and an `is_owner` flag that is true for apps this account publishes (those can be managed in the developer portal). In a client account of a reselling agency, apps the agency's licence covers show the AGENCY's price (`sold_by_agency: true`, bought with apps.start_reseller_checkout) or are free (`included_by_agency: true`) instead of the marketplace's own price.

Parameters

FieldTypeRequiredDescription
limitintegeroptionalMax rows to return (1–100). Default: 25
offsetintegeroptionalRows to skip. Default: 0
categorystringoptionalOnly apps in this category.
querystringoptionalText to match in the app name.

Example

curl -X POST https://app.chirply.io/api/v1/actions/apps.list_directory \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 25,
    "offset": 0
  }'
Test with your API key

Over MCP the same operation is the tool apps_list_directory at https://app.chirply.io/api/mcp, same bearer token, same input.

List installed apps

apps.list_installsreadadmin only

List the apps installed in this account, with their granted scopes and status.

Parameters

FieldTypeRequiredDescription
limitintegeroptionalMax rows to return (1–100). Default: 25
offsetintegeroptionalRows to skip. Default: 0
status"active" | "suspended" | "revoked"optionalOnly installs in this status.

Example

curl -X POST https://app.chirply.io/api/v1/actions/apps.list_installs \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 25,
    "offset": 0
  }'
Test with your API key

Over MCP the same operation is the tool apps_list_installs at https://app.chirply.io/api/mcp, same bearer token, same input.

Installed account apps

apps.list_mobile_pagesread

List the custom pages contributed by active apps installed in this account — first-party native apps (each gated by its own feature flag) plus external/hosted Marketplace apps when the app platform is on. This is the member-safe mobile navigation view: it returns only page labels and in-app routes, never install tokens, secrets, granted scopes, or configuration. Read-only.

Parameters

No parameters — POST an empty body.

Example

curl -X POST https://app.chirply.io/api/v1/actions/apps.list_mobile_pages \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{}'
Test with your API key

Over MCP the same operation is the tool apps_list_mobile_pages at https://app.chirply.io/api/mcp, same bearer token, same input.

View an app's what's new

apps.list_release_notesread

List the published version history and app-owned release notes for one app installed in this account. This is the app's own What's new feed, separate from the product-wide release feed.

Parameters

FieldTypeRequiredDescription
install_idstring (uuid)requiredThe installed app whose release notes to view.

Example

curl -X POST https://app.chirply.io/api/v1/actions/apps.list_release_notes \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "install_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool apps_list_release_notes at https://app.chirply.io/api/mcp, same bearer token, same input.

View app updates

apps.list_updatesread

List version updates for apps installed in this account. Each result identifies the installed version, newest published version, app-specific release notes, and whether an update is available. Marketplace app changes live here instead of the product-wide What's new feed.

Parameters

FieldTypeRequiredDescription
available_onlybooleanoptionalReturn only apps with a newer published version. Set false to include current apps too. Default: true

Example

curl -X POST https://app.chirply.io/api/v1/actions/apps.list_updates \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "available_only": true
  }'
Test with your API key

Over MCP the same operation is the tool apps_list_updates at https://app.chirply.io/api/mcp, same bearer token, same input.

Publish an app version

apps.publish_versionwriteconfirmadmin only

Publish an immutable version of an app: its manifest (the pages/widgets/cards/actions it adds) and, for a PLATFORM-HOSTED app, its `document` — a single self-contained HTML page (inline CSS/JS + the App SDK) served in a sandboxed iframe. This is how an AI agent ships an app it wrote onto the marketplace. It is OUTWARD-FACING AND PERMANENT: a published version cannot be edited or unpublished, a listed app's new installs pin it straight away, and the code in `document` runs inside other people's accounts. Version labels are unique per app, so a mistake can only be superseded, never withdrawn.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
app_idstring (uuid)requiredThe app to publish a version of.
versionstringrequiredVersion label, unique within the app, e.g. '1.0.0'.
manifestobjectoptionalThe app manifest: `pages`/`widgets`/`cards` are UI surfaces; `actions` are named operations the app contributes to the platform's action pickers. For a hosted app the app reads chirply.context.view to know which surface it's rendering. Default: {}
manifest.pagesobject[]optionalCustom pages the app adds to the workspace nav.
manifest.pages[].keystringrequiredURL-safe id — the last segment of /apps/<install>/<key>. Permanent.
manifest.pages[].labelstringrequiredThe nav label a user sees.
manifest.pages[].pathstringoptionalEntry path on the app's base URL, e.g. '/panel'. Same origin only. Default: "/"
manifest.pages[].iconstringoptionalOptional icon hint (a lucide name); a default is used when omitted.
manifest.widgetsobject[]optionalDashboard widgets the app makes available (they launch to the Customize tray).
manifest.widgets[].keystringrequiredURL-safe id for this widget. Permanent.
manifest.widgets[].labelstringrequiredThe widget's title on the dashboard.
manifest.widgets[].pathstringoptionalEntry path on the app's base URL for the widget UI. Same origin only. Default: "/"
manifest.widgets[].defaultSpanintegeroptionalDefault width in 12-column grid units. Defaults to 6 (half).
manifest.cardsobject[]optionalCards the app shows on a contact record (given the contact id).
manifest.cards[].keystringrequiredURL-safe id for this card. Permanent.
manifest.cards[].labelstringrequiredThe card's title on the contact record.
manifest.cards[].pathstringoptionalEntry path on the app's base URL for the card UI. Same origin only. Default: "/"
manifest.cards[].heightintegeroptionalCard height in pixels. Defaults to 320.
manifest.eventsobjectoptionalPlatform events the app subscribes to (external apps with a backend). Needs the 'events:read' scope.
manifest.events.pathstringoptionalPath on your base URL that receives event POSTs, e.g. '/webhooks'. Same origin only. Default: "/webhooks"
manifest.events.subscribestring[]optionalPlatform event names to receive — the automation trigger names (e.g. 'contact_created', 'message_received', 'deal_won', 'invoice_paid'). Each is delivered as a signed POST. Default: []
manifest.actionsobject[]optionalActions the app contributes to the platform's action pickers.
manifest.actions[].keystringrequiredPermanent action key sent to POST <base URL>/actions.
manifest.actions[].labelstringrequiredThe action name shown in action pickers.
manifest.actions[].descriptionstringrequiredWhat the action does, including any real-world side effect or cost.
manifest.actions[].iconstringoptionalOptional Lucide icon name.
manifest.actions[].fieldsobject[]optionalParameters collected before running the action. Default: []
manifest.actions[].fields[].keystringrequiredStable parameter key sent to the app's action endpoint.
manifest.actions[].fields[].labelstringrequiredThe field label a user sees.
manifest.actions[].fields[].type"text" | "textarea" | "number" | "select"optionalThe input control rendered for this parameter. Default: "text"
manifest.actions[].fields[].optionsobject[]optionalChoices for a select field.
manifest.actions[].fields[].optionalbooleanoptionalWhether the action can run without this value.
manifest.actions[].fields[].placeholderstringoptionalExample value shown inside the field.
manifest.actions[].fields[].hintstringoptionalShort help text shown below the field.
manifest.actions[].fields[].defaultValuestringoptionalInitial value for the field.
manifest.actions[].surfacesarray of ("automation" | "disposition" | "bulk" | "contact")optionalPlaces where users can choose this action. Default: ["automation","disposition","bulk","contact"]
documentstringoptionalFor hosting='hosted' ONLY: the app's full self-contained HTML (inline CSS/JS; include <script src="/apps/sdk.js"></script> and use chirply.call / chirply.data). It is served in a null-origin sandbox. Read the guide via apps.dev_guide first.
notesstringoptionalRelease notes for this version.

Example

curl -X POST https://app.chirply.io/api/v1/actions/apps.publish_version \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
    "version": "example"
  }'
Test with your API key

Over MCP the same operation is the tool apps_publish_version at https://app.chirply.io/api/mcp, same bearer token, same input.

Rotate an install's token

apps.rotate_tokenwriteconfirmadmin only

Issue a fresh access token for an installed app and invalidate the old one immediately. Use if a token may have leaked. The new token is shown once.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
install_idstring (uuid)requiredThe install to rotate the token for.

Example

curl -X POST https://app.chirply.io/api/v1/actions/apps.rotate_token \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "install_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool apps_rotate_token at https://app.chirply.io/api/mcp, same bearer token, same input.

Continue to payment

apps.start_purchasewriteadmin only

Prepare the payment form for a PAID app in THIS account. Creates an internal pending order and may create a short-lived Stripe CustomerSession to show an existing saved card; it does not create a Stripe PaymentIntent, charge money, or install the app. Submit payment details with apps.complete_purchase. Free apps use apps.install instead. Refused in a client account whose agency resells the app: an app the agency sells is bought with apps.start_reseller_checkout (paid to the agency), and one the agency includes installs free.

Parameters

FieldTypeRequiredDescription
price_option_idstringoptionalThe buyer-selected price option id from the listing.
instance_namestringoptionalName for this paid install.
app_idstring (uuid)optionalThe paid app to buy (by id).
slugstringoptionalThe paid app to buy (by slug).
grant_scopesstring[]optionalScopes to grant the install once paid — within the app's requested_scopes. Default: []

Example

curl -X POST https://app.chirply.io/api/v1/actions/apps.start_purchase \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "price_option_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
    "instance_name": "Example"
  }'
Test with your API key

Over MCP the same operation is the tool apps_start_purchase at https://app.chirply.io/api/mcp, same bearer token, same input.

Buy from your agency

apps.start_reseller_checkoutwriteadmin only

For a client account whose agency sells this app at its own price: open a Stripe Checkout page on the AGENCY's own Stripe account and return its URL for a person to pay on. Creating it charges nothing — the buyer enters their card on Stripe's page, the money goes to the agency (the platform takes no cut), and the app then switches on in this account automatically. Creates a pending sale the agency can see, and on first sale the app's product on the agency's Stripe. Refused when the agency does not sell the app (use apps.start_purchase or apps.install), when this account already owns it, or when the agency has not connected a Stripe account that can take live payments.

Parameters

FieldTypeRequiredDescription
app_idstring (uuid)optionalThe app to buy from the agency (by id). Give this or slug.
slugstringoptionalThe app to buy from the agency (by marketplace slug).
return_originstringoptionalThe app address the buyer is signed in on now, e.g. https://app.youragency.com, so Stripe sends them back there after paying. Honoured only when it is this account's own app address or the platform's; anything else returns them to this account's branded app address.

Example

curl -X POST https://app.chirply.io/api/v1/actions/apps.start_reseller_checkout \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
    "slug": "example"
  }'
Test with your API key

Over MCP the same operation is the tool apps_start_reseller_checkout at https://app.chirply.io/api/mcp, same bearer token, same input.

App install stats

apps.statsreadadmin only

For an app your agency OWNS, how many accounts have installed it — total, active, revoked, and suspended. This is your developer analytics: it counts installs across all accounts (aggregate only, it never reveals which accounts).

Parameters

FieldTypeRequiredDescription
app_idstring (uuid)requiredThe app to get install stats for.

Example

curl -X POST https://app.chirply.io/api/v1/actions/apps.stats \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool apps_stats at https://app.chirply.io/api/mcp, same bearer token, same input.

Submit an app for review

apps.submit_for_reviewwriteconfirmadmin only

Move a draft app into the platform review queue so it can be approved and listed on the marketplace. This hands the app, its published code and its listing copy to platform reviewers outside this agency, and approval puts it in front of every account on the platform. The app must have a published version first.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
app_idstring (uuid)requiredThe app to submit.

Example

curl -X POST https://app.chirply.io/api/v1/actions/apps.submit_for_review \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool apps_submit_for_review at https://app.chirply.io/api/mcp, same bearer token, same input.

Uninstall an app

apps.uninstallwriteconfirmadmin only

Revoke an app's install in this account. Its access token stops working immediately and the app can no longer reach any of this account's data. If the app is on a paid subscription this ALSO cancels that subscription at the end of the current period — billing stops, access continues until the period ends, and it can be reinstalled free until then, after which it switches off. Uninstalling never refunds and never destroys a one-time purchase: an app bought outright can always be reinstalled at no charge.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
install_idstring (uuid)requiredThe install to revoke.

Example

curl -X POST https://app.chirply.io/api/v1/actions/apps.uninstall \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "install_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool apps_uninstall at https://app.chirply.io/api/mcp, same bearer token, same input.

Remove from client accounts

apps.uninstall_for_clientwriteconfirmadmin only

Run from an AGENCY account: uninstall one of the agency's OWN apps from chosen client accounts directly under it. In each account every active install of the app is revoked — its access token stops working immediately, the app can no longer reach that account's data, and its pages, widgets and contact cards disappear for the client's team. Anything the app already created in the account stays. Each removal is recorded in that client account's access log. It never touches money: an account that BOUGHT the app itself (a paid one-time purchase or a live subscription) is refused, because that purchase is the client's to keep or cancel — they uninstall it from their own account. Works in suspended and cancelled client accounts too. Gates: owner or admin of the agency, the agency's own app, client accounts directly under the agency, and an open access window for any client that requires approval before its agency acts inside it. Each account is handled on its own, so a refused one does not stop the others — read `failed` and each result's `error`. Up to 50 accounts per call.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
app_idstring (uuid)requiredThe agency's own app to remove.
account_idsarray of (string (uuid))requiredThe client accounts to remove the app from.

Example

curl -X POST https://app.chirply.io/api/v1/actions/apps.uninstall_for_client \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
    "account_ids": [
      "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
    ]
  }'
Test with your API key

Over MCP the same operation is the tool apps_uninstall_for_client at https://app.chirply.io/api/mcp, same bearer token, same input.

Uninstall a built-in app

apps.uninstall_nativewriteconfirmadmin only

Turn OFF one of the platform's built-in (native) apps for this account (Browser Agent ('browser-agent'), Directories ('directories'), Domain Leads ('domain-leads'), Desk Phones ('desk-phones'), Business Cards ('business-cards'), Martial Arts Gym ('martial-arts-gym'), GoHighLevel ('gohighlevel'), Quotes & Proposals ('proposals'), Project Preview ('project-preview'), Restaurant ('restaurant'), Shopify Commerce ('shopify'), Klaviyo ('klaviyo'), Loyalty Cards ('loyalty-cards'), Video Meetings ('video-meetings'), Webinars ('webinars')) — the trash-can Uninstall on the Apps screen. The feature's screens disappear from the account and, for integration apps like GoHighLevel and Klaviyo, their capability domains start refusing with app_required. If the app is on a paid subscription this ALSO cancels that subscription at the end of the current paid period — billing stops, and the app can be reinstalled free until the period runs out. Uninstalling never refunds and never destroys a one-time purchase (an app bought outright reinstalls free forever, via apps.install_native), and data the app already imported into this account stays.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
slugstringrequiredThe native app's slug to switch off, e.g. 'restaurant', 'klaviyo', 'gohighlevel'.

Example

curl -X POST https://app.chirply.io/api/v1/actions/apps.uninstall_native \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "example"
  }'
Test with your API key

Over MCP the same operation is the tool apps_uninstall_native at https://app.chirply.io/api/mcp, same bearer token, same input.

Edit an app

apps.updatewriteadmin only

Update an app's details, pricing, requested scopes, or visibility (private/unlisted). Doesn't change review status. Omitted fields are left alone. This edits a LISTED app too, not only a draft: the name, copy and price change on the public marketplace card immediately, with no re-review, and price_cents is what the next buyer is really charged. Repointing external_base_url moves every installed copy's UI to a different server.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe app to edit.
namestringoptionalDisplay name shown on the marketplace card.
taglinestring (or null)optionalOne-line pitch for the card.
descriptionstring (or null)optionalFull description for the listing page.
categorystring (or null)optionalMarketplace category, e.g. 'Telephony'.
icon_urlstring (uri) (or null)optionalHTTPS URL of the app's square icon (upload via POST /api/apps/images).
screenshotsarray of (string (uri))optionalReplaces the app's screenshot list.
hosting"external" | "hosted"optional'external' = you host the app UI yourself and register its HTTPS URL; 'hosted' = the app is a single self-contained HTML document Chirply serves in a sandboxed iframe (publish it with apps.publish_version).
external_base_urlstring (uri) (or null)optionalFor 'external' hosting: the HTTPS URL the app UI is loaded from. Every page/widget/card path is resolved against it, so changing it repoints the app's whole UI for everyone who has it installed.
requested_scopesstring[]optionalReplaces the app's requested-scope list.
pricing_kind"free" | "one_time" | "subscription"optionalHow the app is sold — free, one-time, or a recurring subscription. Buyers are charged for real; see apps.start_purchase / apps.complete_purchase.
price_centsintegeroptionalPrice in integer cents (2900 = $29.00). Real money, charged to the buyer.
pricing_optionsobject[]optionalReplaces the buyer-selectable price options. Use an empty array for free.
pricing_options[].idstringrequiredStable identifier for this price option.
pricing_options[].labelstringrequiredBuyer-facing option name, such as Monthly or Lifetime.
pricing_options[].kind"one_time" | "monthly" | "yearly"requiredWhether this is paid once, monthly, or yearly.
pricing_options[].amount_centsintegerrequiredRegular price in the app currency, in cents.
pricing_options[].sale_amount_centsinteger (or null)optionalTemporary sale price in cents, or null. Default: null
pricing_options[].sale_starts_atstring (date-time) (or null)optionalWhen the sale becomes active, or null for immediately. Default: null
pricing_options[].sale_ends_atstring (date-time) (or null)optionalWhen the sale ends, or null for no scheduled end. Default: null
setup_fee_centsintegeroptionalRequired upfront fee in cents, added to a selected recurring plan.
allow_multiple_installsbooleanoptionalAllow several separately billed installs in one account.
currencystringoptionalISO currency code, lowercase, e.g. 'usd'.
visibility"private" | "unlisted"optionalPublic listing is granted by platform review, not set here.
homepage_urlstring (uri) (or null)optionalYour app's marketing/support homepage.
support_emailstring (email) (or null)optionalWhere installers can reach you.

Example

curl -X POST https://app.chirply.io/api/v1/actions/apps.update \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool apps_update at https://app.chirply.io/api/mcp, same bearer token, same input.

Update in client accounts

apps.update_client_installswriteconfirmadmin only

The bulk version of apps.apply_update, run from an AGENCY account: move the installs of one of the agency's OWN apps in its client accounts to the app's newest published version, all at once. For hosted and external apps this immediately changes the app UI and the event subscriptions running in each of those client accounts. Existing scopes and access tokens are unchanged, nothing is charged, and each update is recorded in that client account's access log. Leave out account_ids to update every client account whose install is behind; name accounts to update only those. Same gates as apps.install_for_client: owner or admin of the agency, the agency's own app (not suspended, not a built-in platform app), active client accounts directly under the agency, and an open access window for any client that requires approval. Each account is handled on its own, so a refused one does not stop the others — read `failed` and each result's `error`. Up to 50 named accounts per call.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
app_idstring (uuid)requiredThe agency's own app whose client-account installs to update.
account_idsarray of (string (uuid))optionalOnly these client accounts. Leave out to update every client account where this app is installed and behind the newest version.

Example

curl -X POST https://app.chirply.io/api/v1/actions/apps.update_client_installs \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool apps_update_client_installs at https://app.chirply.io/api/mcp, same bearer token, same input.

The machine-readable version of this page is GET https://app.chirply.io/api/v1/actions?domain=apps — same operations, with full JSON Schemas. Authentication, errors and rate limits are covered in the API documentation home.