API Reference

Overview

Base URL

API routes live under your market's subdomain, alongside the web pages they power. For example, https://yourmarket.locallygrown.net/api/products. There is no separate API host.

Authentication

• Session cookies only. Authenticated endpoints require a valid auth-session cookie, which is set when a user signs in through the web UI.
• No Bearer tokens. There are no rk_live_* API keys, personal access tokens, or Authorization headers to manage.
• Market context comes from the subdomain. Each request resolves the relevant market from its host, and the authorization layer checks the session user's role against the request's market.

Response format

API routes return JSON. Successful responses look like:

{
  "success": true,
  "data": ...,
  "message": "Optional human-readable note"
}

Errors look like:

{
  "success": false,
  "error": {
    "message": "Human-readable description",
    "code": "ERROR_CODE",
    "details": { ... }
  }
}

Common HTTP status codes

Roles

Authorization checks use six roles:

• Customer — shops, places orders, manages their own account.
• Grower — a vendor in one or more markets; manages their own products and sees orders for items they sell.
• Volunteer — a shopper with help-at-pickup privileges at the market.
• Manager — operates a specific market; scope is limited to that market.
• Admin — market administrator with broader market-level privileges.
• Superuser — platform-wide administrator; not scoped to one market.

A single user can hold more than one role (for example, a grower who is also a manager of the market they sell at). For the impersonation semantics that layer on top of these roles, see Acting as a Customer.

Endpoint groups

The API is organized into groups under /api/. The list below is a map of the main groups rather than a line-by-line reference — endpoint shapes can change, so the source of truth is the server routes in src/routes/api/.

Authentication

• POST /api/auth/signin — create a session from a username and password.
• POST /api/auth/register — create a new customer account.
• POST /api/auth/forgot-password — request a password-reset email.
• POST /api/auth/reset-password — submit a new password with a reset token.
• GET /user/signout — sign out. (This lives outside /api; it clears the session and redirects.)

Shopping

• GET /api/cart, POST /api/cart/add, POST /api/cart/batch-update, POST /api/cart/comment, POST /api/cart/clear — manage the signed-in user's cart.
• Order placement is part of the checkout page flow rather than a dedicated /api/cart/checkout endpoint.

Products

• GET /api/products, POST /api/products, GET|PUT|DELETE /api/products/{id} — list, create, read, update, delete. Growers can only edit their own products; managers/superusers can edit any product in their market.
• POST /api/products/{id}/toggle-availability — activate or deactivate a listing.
• POST /api/products/{id}/toggle-featured — feature or unfeature a product. Growers can feature up to five of their own products per market; the oldest gets unfeatured when the limit is hit.
• POST /api/products/{id}/image — upload a product photo.

Orders

• GET /api/orders, GET /api/orders/{id} — list and fetch orders. Visibility depends on role.
• POST /api/orders/{id}/toggle-complete, POST /api/orders/{id}/prepaid, POST /api/orders/checkout_* — pickup-day operations used by the market admin UI. These are used by market managers during pickup; customers don't hit them directly.

Users and account

• GET /api/users, GET|PUT /api/users/{id} — admin list and per-user fetch/update.
• POST /api/user/deactivate-account — customer self-service account deactivation.

Market

• Market settings, pickup locations, categories, announcements, and email preferences are all under /api/market/. Requires a manager or superuser session for the target market.

Reports and metrics

• /api/market/metrics, /api/market/insights and /orders/*.csv endpoints back the admin reports UI. See the Reports guide for what's actually used in the UI.

Health

• GET /api/health, GET /api/health/db-pool, GET /api/health/queues — unauthenticated liveness/readiness checks.

Webhooks

Inbound webhooks from Stripe and Mailgun only — no outbound events. See the Webhooks guide.

Rate limiting

Specific endpoints — sign-in, sign-up, password-reset, and the Stripe webhook — apply targeted rate limits per IP to protect against abuse. There is no global X-RateLimit-* header scheme on the API. If you hit a limit you'll get a 429 with a standard error payload.