Preview

6 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.

Delete preview

preview.delete_renderwriteconfirm

Permanently remove one preview from the archive. The image itself stays in the media library, so anything already attached to a proposal or sent to a customer keeps working — this removes the archive entry only. Previews cost money to generate and cannot be recreated identically, so deleting is rarely the right move. Requires the AI Project Preview app (a purchase from the App Marketplace) to be installed in this account; without it the call returns 403 app_required.

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

Field	Type	Required	Description
id	string (uuid)	required	Id of the preview to remove from the archive.

Example

curl -X POST https://app.chirply.io/api/v1/actions/preview.delete_render \
  -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 preview_delete_render at https://app.chirply.io/api/mcp, same bearer token, same input.

Preview settings

preview.get_settingsread

The account's preview configuration: which design packs are switched on, and whether the public lead-capture page is live — its address, its wording, and the monthly render cap that limits what the public can spend. Requires the AI Project Preview app (a purchase from the App Marketplace) to be installed in this account; without it the call returns 403 app_required.

Parameters

No parameters — POST an empty body.

Example

curl -X POST https://app.chirply.io/api/v1/actions/preview.get_settings \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{}'

Test with your API key

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

Design packs

preview.list_packsread

List the design packs available for previews — one per trade — with the choices, stackable layers and product styles each offers. Call this first: the ids returned here are what preview.render expects, and they differ per pack. Requires the AI Project Preview app (a purchase from the App Marketplace) to be installed in this account; without it the call returns 403 app_required.

Parameters

Field	Type	Required	Description
pack	string	optional	Return just this pack, with its full option lists.

Example

curl -X POST https://app.chirply.io/api/v1/actions/preview.list_packs \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "pack": "example"
  }'

Test with your API key

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

Preview history

preview.list_rendersread

List previews already generated, newest first, with the permanent image URLs. Every render is kept — they cost money to produce — so this is the archive to pull from when attaching a before/after to a proposal or a follow-up message. Requires the AI Project Preview app (a purchase from the App Marketplace) to be installed in this account; without it the call returns 403 app_required.

Parameters

Field	Type	Required	Description
limit	integer	optional	Max rows to return (1–100). Default: 25
offset	integer	optional	Rows to skip. Default: 0
contact_id	string (uuid)	optional	Only previews for this customer.
session_id	string	optional	Only previews from one sitting — every angle and style together.
source	"studio" \| "funnel"	optional	'studio' for staff-generated, 'funnel' for ones the public page produced.
pack	"lighting" \| "roofing" \| "exterior-paint" \| "landscaping"	optional	Only previews using this design pack.

Example

curl -X POST https://app.chirply.io/api/v1/actions/preview.list_renders \
  -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 preview_list_renders at https://app.chirply.io/api/mcp, same bearer token, same input.

Generate preview

preview.renderwriteconfirm

Edit a photo of a customer's property to show the finished work on THAT building — the point being that it is their house, not a stock example. SPENDS REAL MONEY: every call runs an image model on this account's own OpenRouter key and is billed to them directly, with no caching, and requesting several product styles bills once per style. Takes 20-60 seconds. The photo goes in as a base64 data URL; the result is archived to the media library and returned as a permanent URL. Requires the AI Project Preview app (a purchase from the App Marketplace) to be installed in this account; without it the call returns 403 app_required.

Parameters

Field	Type	Required	Description
pack	string	required	Built-in or business-created project type id from preview.list_packs.
photo	string	required	The customer's own photo of the property, as a base64 data URL. A straight-on daylight shot of the elevation being worked on gives the best result.
mode	"choice" \| "stack" \| "recommend"	optional	'stack' combines the primary choice and layers you name. 'recommend' ignores them and renders the pack's complete designer's-choice package, for when the customer has no idea what they want. ('draw' mode exists in the app but needs a hand-marked image and is not offered here.) Default: "stack"
primary	string	optional	Id of the single-choice option for this pack, e.g. a roofline colour. Ids come from preview.list_packs; a pack may have none.
layers	string[]	optional	Ids of stackable layers to add. Ids not in the pack are ignored. Default: []
styles	string[]	optional	Product-style ids to render as a side-by-side comparison — ONE IMAGE AND ONE CHARGE PER STYLE. Leave empty for a single render. Default: []
note	string	optional	A specific request from the customer, honoured only if it's about this trade.
angle	string	optional	Which view this is, e.g. 'Front' or 'Left side'. Groups multi-angle sessions.
contact_id	string (uuid)	optional	The customer this is for. Files the render on their record.
proposal_id	string (uuid)	optional	Draft proposal to attach the interactive before/after to. Requires Quotes & Proposals in the same account; accepted proposals are immutable.
session_id	string	optional	Groups renders from one sitting — several angles, or several styles. Pass the same value across related calls; omit it and a fresh one is minted.

Example

curl -X POST https://app.chirply.io/api/v1/actions/preview.render \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "pack": "example",
    "photo": "example"
  }'

Test with your API key

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

Save preview settings

preview.save_settingswriteconfirmadmin only

Update which design packs are offered and configure the public lead-capture page. TURNING THE PUBLIC PAGE ON PUBLISHES A URL ANYONE CAN USE, and every submission spends this account's own AI credit — which is what the monthly cap is for. Set the cap to what you are willing to spend on strangers in a month, because that is exactly what it controls. Requires the AI Project Preview app (a purchase from the App Marketplace) to be installed in this account; without it the call returns 403 app_required.

Parameters

Field	Type	Required	Description
enabled_packs	array of ("lighting" \| "roofing" \| "exterior-paint" \| "landscaping")	optional	Built-in design packs to offer. With custom_projects present, an empty array means custom-only; without them it keeps the built-in defaults.
custom_projects	object[]	optional	Business-created project types that make the widget fit this account's services.
custom_projects[].id	string	required	Stable project type id used by preview.render.
custom_projects[].label	string	required	Customer-facing project name, such as 'Kitchen remodel'.
custom_projects[].description	string	required	Short explanation shown in the project type picker.
custom_projects[].photoLabel	string	required	Heading for the before-photo step.
custom_projects[].photoHint	string	required	Instructions for taking a useful source photo.
custom_projects[].requestLabel	string	required	Question asking the customer what finished result they want.
custom_projects[].requestPlaceholder	string	required	Concrete example answer shown in the request field.
custom_projects[].transformationPrompt	string	required	Business-authored AI rules defining the allowed transformation and what must stay unchanged.
funnel_enabled	boolean	optional	Whether the public preview page is live. Requires a funnel_slug to be set.
funnel_slug	string (or null)	optional	The public address: /see/<slug>. Unique across the whole platform, so a common word may be taken. Usually the business name.
funnel_headline	string (or null)	optional	Headline on the public page, e.g. 'See it on your own home first.'
funnel_subhead	string (or null)	optional	The line under the headline, setting expectations about what happens next.
funnel_require_phone	boolean	optional	Require a phone number as well as a name. On gets better leads; off gets more of them.
funnel_monthly_cap	integer	optional	Maximum renders the PUBLIC page may generate per calendar month. Past it the page still captures the lead but says previews are paused. To stop the page entirely, set funnel_enabled to false rather than setting a cap of 1.

Example

curl -X POST https://app.chirply.io/api/v1/actions/preview.save_settings \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "funnel_enabled": true,
    "funnel_slug": "example"
  }'

Test with your API key

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