API Contract
Use the frozen Soar App API v1 and separate Better Auth HTTP contract as the platform sources of truth.
SoarStarter has two public HTTP boundaries. They are versioned and maintained separately.
Soar App API v1
market/pilot/openapi.yaml is the canonical OpenAPI 3.1 contract. It covers /api/app/v1 business operations:
- Profile read and update.
- Todo list, create, update, delete, clear, and reorder.
- Native device-token registration and deletion.
- Current-user APNs test push.
- Subscription snapshot, checkout, and management portal behavior.
- Presigned upload creation and completion.
- Cascading account deletion.
Successful responses use { "success": true, "data": ... }. Errors use { "success": false, "error": { "code", "message", "requestId" } }. v1 accepts additive, backward-compatible changes; breaking changes require v2.
Better Auth HTTP
market/pilot/auth-http.md defines the separate /api/auth/* native contract. It covers signed Bearer transport, trusted Origin, set-auth-token, email/password, OTP, native ID-token sign-in, session query, revocation, and credential changes.
Authentication endpoints are intentionally absent from the OpenAPI business contract. Do not copy them under /api/app/v1 or invent a second session transport.
Host docs explain framework-specific wiring; client docs explain secure storage and configuration. Endpoint schemas remain canonical here rather than being rewritten per template.