> ## 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. # AgentLink API overview > Externally reachable API surface including public discovery, MCP proxy, admin APIs, webhooks, and billing. # AgentLink API overview AgentLink exposes three categories of endpoints: public discovery and proxy, authenticated embedded-admin APIs, and webhooks. ## Public discovery endpoints These routes are CORS-enabled and intended for external agents and browser-based clients. The shop-scoped discovery and proxy routes carry shop validation, rate limits, and per-request installation verification; `/healthz` is an unauthenticated liveness probe. | Endpoint | Description | Method | | - | - | - | | `/.well-known/ucp?shop=` | UCP discovery profile with ECDSA P-256/SHA-256 signature | GET | | `/ucp/:shop/.well-known/ucp` | Path-based UCP profile | GET | | `/mcp/:shop/storefront` | Storefront MCP tool proxy | POST | | `/mcp/:shop/ucp` | UCP MCP tool proxy | POST | | `/schema/:shop.json` | Schema.org product feed from Admin GraphQL | GET | | `/llms.txt?shop=` | Public llms.txt index for AI tooling | GET | | `/healthz` | Health check returning release SHA and app name | GET | ### Curl example Set `APP_ORIGIN` to the app's HTTPS origin, without a trailing slash. Fetch a shop's public UCP discovery profile: ```bash theme={null} curl --fail-with-body "${APP_ORIGIN:?Set APP_ORIGIN}/.well-known/ucp?shop=example.myshopify.com" ``` ### UCP profile discovery The `/.well-known/ucp` endpoint returns a signed JSON profile with merchant identity, endpoints, capabilities, payment handlers, and policies. When a profile is active and an audit has been run, the response includes a `x-agentic-profile-signature` header containing the ECDSA P-256/SHA-256 signature of the compact JSON body. ### MCP proxy `POST /mcp/:shop/:type` forwards JSON-RPC MCP requests to the shop's configured MCP endpoint. The proxy: * Supports `Authorization` and `MCP-Protocol-Version` header forwarding. * Enforces per-shop rate limits (120 requests per minute). * Records SHA-256 request/response hashes with AES-256-GCM encrypted replay bodies. * Returns `x-agentic-request-id` header for log correlation. * Rejects bodies over 1 MiB. * Requires an active subscription or developer entitlement. ## Authenticated embedded-admin APIs These routes require a Shopify App Bridge session token and are scoped to the authenticated shop. Merchant mutation routes require owner/admin subject. | Endpoint | Description | Method | Auth | | - | - | - | - | | `/api/readiness` | Latest audit result | GET | Session token | | `/api/audit/run` | Run a new readiness audit (consumes plan quota) | POST | Merchant admin | | `/api/profile` | Get or update agent profile | GET/POST | Merchant admin | | `/api/setup-status` | Onboarding setup status and step list | GET | Session token | | `/api/setup-status/skip` | Dismiss setup wizard | POST | Merchant admin | | `/api/traffic` | 24-hour traffic count and latest 50 log entries | GET | Session token | | `/api/settings/openai-key` | OpenAI key mode (GET) or save/clear key (POST) | GET/POST | Merchant admin | ### Integration APIs These are under the `/api/integrations` prefix and require merchant admin auth: | Endpoint | Description | Method | | - | - | - | | `/api/integrations/auth0/token` | Issue agency dashboard bearer token | POST | | `/api/integrations/tts` | ElevenLabs text-to-speech | POST | | `/api/integrations/sms` | Twilio SMS handoff notices | POST | | `/api/integrations/fax` | Sinch eFax notifications | POST | | `/api/integrations/preflight` | Operator integration preflight | POST | | `/api/integrations/knowledge` | List or store knowledge documents (create respects plan caps) | GET/POST | | `/api/integrations/knowledge/search` | Semantic search by cosine similarity | POST | ### Privacy exports | Endpoint | Description | Method | | - | - | - | | `/api/privacy-exports/:id/download` | Download customer data export (signed download token, or an authenticated merchant admin session) | GET/POST | ## Billing routes Authentication varies by route. `/billing/plans` does not require authentication. `/billing/callback` verifies the signed, single-use billing state returned after Shopify billing approval. All other routes require a Shopify App Bridge session token for a merchant administrator. | Endpoint | Description | Method | Authentication | | - | - | - | - | | `/billing/plans` | Plan catalog with current prices | GET | None | | `/billing/status` | Subscription state, entitlement, trial history, and developer override | GET | Merchant admin session token | | `/billing/subscribe` | Create or start subscription (defaults to Foundation when plan is omitted) | POST | Merchant admin session token | | `/billing/change` | Change subscription plan | POST | Merchant admin session token | | `/billing/cancel` | Cancel subscription | POST | Merchant admin session token | | `/billing/limits` | Effective plan limits for the current shop | GET | Merchant admin session token | | `/billing/callback` | Return target after Shopify billing approval | GET | Signed, single-use billing state | ## Agency dashboard Under the `/agency` prefix, authenticated by an app-issued HS256 bearer token: | Endpoint | Description | Method | | - | - | - | | `/agency/dashboard` | Read-only shop dashboard with readiness score and 24-hour traffic count | GET | ## Webhooks AgentLink registers Shopify webhooks under the `/webhooks` prefix: | Topic | Handler path | Description | | - | - | - | | `app/uninstalled` | `/webhooks/app_uninstalled` | Clean up on uninstall | | `app_subscriptions/update` | `/webhooks/app_subscriptions_update` | Sync subscription state | | `products/create` | `/webhooks/drift` | Record product schema drift | | `products/update` | `/webhooks/drift` | Record product schema drift | | `products/delete` | `/webhooks/drift` | Record product schema drift | | `inventory_levels/update` | `/webhooks/drift` | Record inventory drift | | `shop/update` | `/webhooks/drift` | Record shop identity drift and refresh primary domain | | `customers/data_request` | `/webhooks/privacy` | Generate customer data export | | `customers/redact` | `/webhooks/privacy` | Purge customer data and artifacts | | `shop/redact` | `/webhooks/privacy` | Delete all shop data and R2 snapshots | All webhooks use HMAC verification. Drift webhooks deduplicate on signed payload hash. Privacy webhooks are transactional, with paginated storage and retry support. [Pcnaid Documentation](https://docs.pcnaid.com/namespace/index.md) › [Shopify Ecosystem](https://docs.pcnaid.com/hubs/shopify-ecosystem/index.md) › [AgentLink](https://docs.pcnaid.com/nodes/shopify/agentlink/index.md) › [Developer](https://docs.pcnaid.com/nodes/shopify/agentlink/developer/index) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.