Agent API

Northbound Coffee Roasters for developers and AI agents

Browse public content anonymously. Private data and every action require a scope-restricted API key.

Model Context Protocol

Streamable HTTP endpoint: /api/mcp. Server card: /.well-known/mcp/server-card.json (legacy alias: /.well-known/mcp.json).

Anonymous clients discover only:

products.search
products.get
categories.list
site.list_pages
site.get_page

REST & OpenAPI 3.1

POST /api/v1/tools/<tool.name>. Open the generated OpenAPI document. Discover the API catalog.

curl -X POST https://demo.cartwright.app/api/v1/tools/products.search \
  -H 'Content-Type: application/json' \
  -d '{"q":"aviator","limit":5}'

Authentication and scopes

Send Authorization: Bearer sb_live_…. The key never receives more access than its owner-assigned scopes. Writes, customers, orders, checkout and administration are never anonymous.

Rate limits

Anonymous requests have a burst allowance of 60 per IP. Requests attempting Bearer authentication have a separate pre-auth allowance of 120 per IP, enforced before any database lookup. Responses include current structured RateLimit-Policy and RateLimit fields plus the legacy RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset fields. A 429 also includes Retry-After.

Problem details

Errors use application/problem+json with type, title, status, detail, instance, code and resolution. The legacy ok/error fields remain for one compatibility window.

API versioning & deprecation

Stable REST operations use a major-versioned URL prefix, currently /api/v1. Additive fields may be added within v1; breaking changes require a new major prefix.

Before a stable version is removed, a migration guide is published. Deprecation is signaled with RFC 9745 Deprecation and Link headers, and a dated Sunset header is announced at least 90 days before removal.

Cartwright CLI

Start a new website or shop with the official npm package: create-cartwright.

npx create-cartwright@latest