Public API & MCP server
Manage sorting strategies, collection assignments, and on-demand sorts from external tools and AI assistants like Claude.
Availability & authentication
Availability: paid plans (grandfathered legacy free shops included). Authentication: per-shop API key, generated in the app under Settings → Integrations, passed as Authorization: Bearer <key>. Keys are shown once at creation and stored hashed — revoke them any time from the same page. Your store's API base URL and MCP endpoint URL are both shown on the Integrations page.
REST API
Base path: /public-api/v1 (full base URL shown on your Integrations page).
| Method | Path | Description |
|---|---|---|
GET | /me | Verify the key; returns shop, plan, and key label |
GET | /strategies | List strategies (without layer detail) |
GET | /strategies/:id | One strategy with full layer configuration |
GET | /collections?active=true | Managed collections with strategy, status, last sorted |
GET | /collections/:collectionId | One collection's config, strategy, and pending job |
PUT | /collections/:collectionId | Body { strategyId?, isSortingActive? } — assign strategy and/or toggle sorting |
POST | /collections/:collectionId/sort | Queue an on-demand sort (priority) |
GET | /sort-jobs | Queued/processing sort jobs, newest first |
:collectionId accepts a numeric Shopify id or a gid://shopify/Collection/<id> GID.
Errors & limits
Errors are { error: <code>, message } with meaningful HTTP status codes:
401— invalid key403— free plan, blocked account, or managed-collections plan limit reached on activation404— unknown strategy / unmanaged collection409— sorting inactive or plan limit exceeded429— rate limit (60 requests/min per key) or sort cooldown (2 min per collection; the response includes the next eligible time)
Behavior notes
- Changing the strategy on an active collection automatically queues a re-sort (same as the app UI).
- Sort triggering is idempotent: if a job is already queued for the collection, the existing job is returned instead of queueing a duplicate.
- API-triggered sorts are logged in the collection's event history ("Sort triggered via API").
MCP endpoint (AI assistants)
The MCP server speaks streamable HTTP at POST /mcp (endpoint URL on your Integrations page). Two ways to authenticate:
OAuth — claude.ai custom connectors
The server is a full OAuth 2.1 authorization server (discovery metadata, dynamic client registration, PKCE, refresh-token rotation, revocation). To connect:
- In the app, open Settings → Integrations and generate a connect code (10-minute expiry, single use).
- In claude.ai: Settings → Connectors → Add custom connector → paste your MCP server URL.
- Claude redirects to the consent page — enter the connect code to bind the connector to your store.
Access tokens last 1 hour; refresh tokens 30 days (rotated on use). All tokens are stored hashed and cleaned up if you uninstall the app.
Bearer API key — header-capable clients
For clients that support custom headers, e.g. Claude Code:
claude mcp add collection-sort --transport http https://<your-mcp-url>/mcp \
--header "Authorization: Bearer jcs_..."Available tools
list_strategies, get_strategy, list_collections, get_collection_config, set_collection_sorting, sort_collection_now, list_sort_jobs — thin wrappers over the same operations layer as the REST API, so behavior, plan gating, and limits are identical.
Not exposed (v1)
Strategy creation, editing, and deletion are deliberately not exposed in v1. Manage strategy rules from the app UI.