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=<domain>`	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=<domain>`	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:

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 › Shopify Ecosystem › AgentLink › Developer

Start here

Documentation hubs

Legal

Shared legal

AgentLink API overview

AgentLink API overview

Public discovery endpoints

Curl example

UCP profile discovery

MCP proxy

Authenticated embedded-admin APIs

Integration APIs

Privacy exports

Billing routes

Agency dashboard

Webhooks

​AgentLink API overview

​Public discovery endpoints

​Curl example

​UCP profile discovery

​MCP proxy

​Authenticated embedded-admin APIs

​Integration APIs

​Privacy exports

​Billing routes

​Agency dashboard

​Webhooks

AgentLink API overview

Public discovery endpoints

Curl example

UCP profile discovery

MCP proxy

Authenticated embedded-admin APIs

Integration APIs

Privacy exports

Billing routes

Agency dashboard

Webhooks