> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pcnaid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GrowthAgent API reference

> Externally reachable API surface — public endpoints, webhooks, billing, and embedded admin routes.

# 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:

```bash theme={null}
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):

```bash theme={null}
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](https://docs.pcnaid.com/nodes/shopify/growthagent/developer/architecture-overview.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.