GrowthAgent API reference

Public (unauthenticated) endpoints

Method	Path	Description
GET	`/health`	Health check — returns JSON with build SHA, binding presence
GET	`/healthz`	Health check alias (same as `/health`)
GET	`/`	Health response, or embedded admin app when `?shop=` is present
GET	`/marketing`	Public marketing page with JSON-LD structured data
GET	`/favicon.ico`	Static favicon
GET	`/privacy`	301 redirect to Privacy Policy on docs.pcnaid.com
GET	`/terms`	301 redirect to Terms of Service on docs.pcnaid.com
GET	`/legal`	301 redirect to Terms of Service on docs.pcnaid.com
GET	`/legal/privacy`	301 redirect to Privacy Policy on docs.pcnaid.com
GET	`/legal/terms`	301 redirect to Terms of Service on docs.pcnaid.com

Shopper chat endpoints (public, rate-limited)

Method	Path	Description
OPTIONS	`/chat`	CORS preflight
POST	`/chat`	Send a shopper message and receive an AI answer. Rate-limited per IP. Shop-validated.
OPTIONS	`/proxy/chat`	CORS preflight (proxy alias)
POST	`/proxy/chat`	Chat message (proxy alias)
OPTIONS	`/chat/feedback`	CORS preflight
POST	`/chat/feedback`	Submit feedback on a chat answer. Rate-limited.
OPTIONS	`/proxy/chat/feedback`	CORS preflight
POST	`/proxy/chat/feedback`	Feedback (proxy alias)
GET	`/voice/:messageId`	ElevenLabs TTS audio stream for a specific assistant message
GET	`/handoff-faxes/:ticketId/document`	Signed, expiring PDF handoff summary document

OAuth endpoints

Method	Path	Description
GET	`/install`	Begin Shopify OAuth flow
GET	`/auth/install`	Begin Shopify OAuth flow (alias)
GET	`/auth/callback`	Complete Shopify OAuth — exchange code for tokens

Webhook endpoints

Method	Path	Topics handled
POST	`/webhooks/app_uninstalled`	`app/uninstalled`
POST	`/webhooks/app_subscriptions_update`	`app_subscriptions/update`
POST	`/webhooks/sync`	`products/create`, `products/update`, `products/delete`, `inventory_levels/update`
POST	`/webhooks/orders`	`orders/create`
POST	`/webhooks/shop_update`	`shop/update`
POST	`/webhooks/privacy`	`customers/data_request`, `customers/redact`, `shop/redact`

Set APP_ORIGIN to the app’s HTTPS origin, without a trailing slash. Health check example:

curl --fail-with-body "${APP_ORIGIN:?Set APP_ORIGIN}/health"

Chat request example. The body is a JSON object with shop (the store domain), sessionId (a storefront session identifier, 8 to 160 characters) and message (the shopper’s text, up to 2,000 characters):

curl -X POST "${APP_ORIGIN:?Set APP_ORIGIN}/chat" \
  -H "Content-Type: application/json" \
  -d '{"shop":"example.myshopify.com","sessionId":"session-12345678","message":"What is your return policy?"}'

Billing endpoints (requires embedded admin session)

Method	Path	Description
GET	`/billing/plans`	List available plans and prices
GET	`/billing/status`	Current subscription status (refreshes from Shopify)
POST	`/billing/subscribe`	Create a subscription (defaults to Starter)
POST	`/billing/change`	Change plan
GET	`/billing/callback`	Billing OAuth callback

Embedded admin pages (requires Shopify session token)

Method	Path	Description
GET	`/app`	Home dashboard — metrics, conversations, setup status
GET	`/app/knowledge`	Store knowledge management
GET	`/app/simulation`	Simulation/testing page
GET	`/app/settings`	Settings — brand, handoff, localization, AI, connected accounts

Authenticated API (requires admin session)

Method	Path	Description	Paid required
POST	`/api/session/bootstrap`	Refresh session cookie	No
GET	`/api/access-status`	Plan label, domain, entitlement status	No
GET	`/api/setup-status`	Onboarding steps, completion, skipped-at	No
POST	`/api/setup-status`	Skip setup dismissal (`{"intent":"skip_setup"}`)	No
GET	`/api/settings`	Read settings (sanitized)	No
POST	`/api/settings`	Save settings	Yes
POST	`/api/knowledge/sync`	Sync catalog, pages, policies	Yes
GET	`/api/metrics`	AI answer and handoff counts (30 days)	No
GET	`/api/conversations`	Recent conversations (latest 25)	No
POST	`/api/simulate`	Run a simulation	Yes

Privacy export download (public with signed proof)

Method	Path	Description
GET	`/api/privacy-exports/:id/download`	Landing page with CSP nonce
POST	`/api/privacy-exports/:id/download`	Download export (verify signed proof or admin session)

Plans and usage

Plan	Handle	Meter
Starter	`starter`	Base recurring + `ai_answer` (analytics only)
Pro	`pro`	Base recurring + `managed_ai_answer` (platform-paid)

Usage meter handles emitted via Shopify App Events: ai_answer, managed_ai_answer, handoff_created, simulation_run, assisted_order, knowledge_sync. Plan prices are set per deployment. Trial days: 0. Plan changes apply immediately. For the full architecture walkthrough, see the architecture overview.

Start here

Documentation hubs

Legal

Shared legal

GrowthAgent API reference

GrowthAgent API reference

Public (unauthenticated) endpoints

Shopper chat endpoints (public, rate-limited)

OAuth endpoints

Webhook endpoints

Billing endpoints (requires embedded admin session)

Embedded admin pages (requires Shopify session token)

Authenticated API (requires admin session)

Privacy export download (public with signed proof)

Plans and usage

​GrowthAgent API reference

​Public (unauthenticated) endpoints

​Shopper chat endpoints (public, rate-limited)

​OAuth endpoints

​Webhook endpoints

​Billing endpoints (requires embedded admin session)

​Embedded admin pages (requires Shopify session token)

​Authenticated API (requires admin session)

​Privacy export download (public with signed proof)

​Plans and usage

GrowthAgent API reference

Public (unauthenticated) endpoints

Shopper chat endpoints (public, rate-limited)

OAuth endpoints

Webhook endpoints

Billing endpoints (requires embedded admin session)

Embedded admin pages (requires Shopify session token)

Authenticated API (requires admin session)

Privacy export download (public with signed proof)

Plans and usage