Agent-friendly Sortiri

Sortiri supports two agent-driven flows: apply for the beta (20 spots) or complete full fitness setup. In both cases the human verifies email before anything enters review or becomes claimable.

Machine-readable spec: /agent.txt · /llms.txt · /agents.json

Beta application (20 spots)

Agent                    Human
  │                        │
  ├─ POST /beta/apply ─────┤
  ├─ Share confirm URL ───►│ Opens /beta/confirm/{token}
  │                        ├─ Confirms email
  ├─ Poll GET /status ─────┤
  │                        │
  │◄── status: accepted ───┤ (manual review)
  ├─ Return welcome links ─► Discord · App Store · setup

Headless apply (email optional — human confirms on confirm page):

curl -X POST "https://ideal-dolphin-65.convex.site/beta/apply" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alex Runner",
    "answers": {
      "whyJoin": "I want early access to an AI coach that tracks training and nutrition together.",
      "goal": "build_muscle",
      "experienceLevel": "intermediate",
      "hasIosDevice": true,
      "weeklyAvailability": "3_4"
    }
  }'

Response:

{
  "applicationToken": "...",
  "status": "pending_confirmation",
  "confirmUrl": "https://sortiri.ai/beta/confirm/...",
  "statusUrl": "https://sortiri.ai/beta/status/...",
  "handoffMessage": "I've applied you for the Sortiri beta..."
}

Poll status: GET https://ideal-dolphin-65.convex.site/beta/status/{applicationToken}

When status === "accepted", the response includes welcomeUrl, discordInviteUrl, appStoreUrl, welcomeVideoUrl, and setupUrl.

Schema: /beta-application.schema.json · Browser fallback: /beta?mode=agent

Onboarding flow overview

Agent                    Human
  │                        │
  ├─ Complete setup ───────┤
  ├─ Create draft token    │
  ├─ Share claim URL/QR ──►│ Opens /claim/{token}
  │                        ├─ Reviews plan summary
  │                        ├─ Verifies email (OTP)
  │                        ├─ Downloads iOS app
  │                        └─ Signs in → quick tour

Path A — Headless HTTP API (recommended)

Create a draft without a browser session:

curl -X POST "https://ideal-dolphin-65.convex.cloud/onboarding/draft" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "answers": { "...": "see agent.txt" }
  }'

Response:

{
  "token": "...",
  "expiresAt": 1234567890123,
  "claimUrl": "https://sortiri.ai/claim/...",
  "statusUrl": "https://ideal-dolphin-65.convex.site/onboarding/draft/status/...",
  "handoffMessage": "Your Sortiri fitness plan is ready..."
}

Schema: /onboarding-draft.schema.json

Drafts expire after 24 hours. Each token can be claimed once. Rate limit: 20/hour.

Path B — Browser automation (fallback)

Open /setup?mode=agent. Each step is a section[data-setup-step][data-setup-ready="true"] with labeled inputs and option buttons (button[name][data-value]). Deep-link with ?step=meals when prior steps are complete.

1. Automate each wizard step using stable selectors (see /agent.txt)
2. Chip steps auto-advance; date/text steps need Continue
3. On finish, receive claim URL + QR code
4. Share with the account owner

Beta browser fallback: /beta?mode=agent with data-beta-step selectors.

Step order (setup): goal → meals → workouts → weigh-ins → gender → units → dob → weight → height → activity → macros → notifications → consent → email.

Female users may see additional steps: pregnancy, cycle tracking, period dates.

Compute macros (API agents)

API requests must include computed targets in answers. Use Mifflin-St Jeor:

• BMR: male = 10×kg + 6.25×cm − 5×age + 5; female/other = 10×kg + 6.25×cm − 5×age − 161
• Activity multiplier: 20→1.2, 40→1.375, 50→1.55, 70→1.725, 90→1.9
• Target calories: lose_fat = max(1200, TDEE−500); build_muscle = TDEE+300; recomp/maintain = TDEE
• Protein: 2.2 g/kg (lose/recomp), 2.0 g/kg (build), 1.6 g/kg (maintain)
• Remaining calories → 55% carbs, 45% fat
• Water ml: clamp(round((kg × 35 × activityMult) / 100) × 100, 1500, 5000)

Required output fields: dailyCalorieGoal, macroProtein, macroCarbs, macroFat, dailyWaterGoalMl

Claim flow (human)

1. Open https://sortiri.ai/claim/{token}
2. Review plan summary
3. Enter email (prefilled if agent provided it) + OTP verification
4. Download iOS app and sign in with same email

What agents cannot do

• Bypass OTP email verification
• Create accounts without human claim step
• Access user data after claim (no post-signup API)
• Complete mobile app onboarding (human does walkthrough in app)

Security

• OTP verification is required — agents cannot bypass email ownership.
• Claim tokens are opaque, single-use, and time-limited (24h).
• The claim page shows a summary before saving.

Full spec: /agent.txt · Support: support@fystash.ai