Documentation Index Fetch the complete documentation index at: https://mintlify.com/ricardomb-tech/surqo/llms.txt
Use this file to discover all available pages before exploring further.
The Users API exposes your Surqo profile, real-time quota consumption, and — for admin accounts — the ability to upgrade any user to the Pro plan. All user endpoints require a valid Supabase JWT in the Authorization: Bearer header. User profiles are created automatically on first authenticated request; the default plan is "free".
Endpoints GET /api/v1/users/me Returns the full profile for the authenticated user, including farm list, quota counters, and computed flags like can_use_ai_analysis.
Rate limit: 60 requests/minute per IP.Response — 200 OK { "user_id" : "uuid" , "email" : "agricultor@ejemplo.com" , "full_name" : "Juan Pérez" , "phone" : null , "bio" : null , "avatar_url" : null , "cover_url" : null , "plan" : "free" , "is_paid" : false , "can_use_ai_analysis" : true , "can_send_email_alert" : true , "email_alerts_this_month" : 3 , "analyses_used" : 2 , "analyses_limit" : 4 , "analyses_remaining" : 2 , "tokens_used" : 1600 , "tokens_limit" : 3200 , "tokens_remaining" : 1600 , "can_use_chat" : true , "farms_count" : 1 , "created_at" : "2026-06-01T00:00:00Z" , "farms" : [ { "id" : "uuid" , "name" : "Finca La Esperanza" , "crop_type" : "maíz" , "area_hectares" : 12.5 , "municipality" : "Montería" , "department" : "Córdoba" } ] }
Show Response field reference
The Supabase Auth UUID for this user. Matches the sub claim in the JWT.
Email address from Supabase Auth.
true when plan == "paid" or the user is an admin.
true when the user has not yet exhausted their analysis quota (always true for Pro and admin accounts).
true for all users — email alerts are unlimited on all plans.
Number of alert emails dispatched for this user’s farms in the current calendar month.
Lifetime count of AI analyses consumed.
Maximum analyses allowed. null for Pro/admin (unlimited).
Remaining analyses before quota is exhausted. null for Pro/admin.
Lifetime output tokens consumed across all AI analyses and chat.
Total token budget. null for Pro/admin (unlimited).
true when the user’s token budget has not been exhausted.
Total farms owned by the user.
List of FarmSummary objects — id, name, crop_type, area_hectares, municipality, department.
PATCH /api/v1/users/me Update the authenticated user’s profile. All fields are optional — only provided fields are updated.
Rate limit: 20 requests/minute per IP.Display name. Maximum 200 characters.
Phone number. Maximum 30 characters.
Short biography. Maximum 500 characters.
URL to the user’s avatar image. Maximum 500 characters.
URL to the user’s cover/banner image. Maximum 500 characters.
Response — 200 OK — Full UserProfileResponse (same as GET /me)GET /api/v1/users/me/plan-limits Returns a structured breakdown of current quota usage. Use this endpoint to check remaining capacity before calling analysis endpoints, and to drive progress indicators in your UI.
Response — 200 OK { "plan" : "free" , "farms" : { "used" : 1 , "limit" : 1 , "unlimited" : false , "remaining" : 0 }, "ai_analysis" : { "allowed" : true , "used" : 2 , "limit" : 4 , "remaining" : 2 , "tokens_used" : 1600 , "tokens_limit" : 3200 , "max_tokens_per_analysis" : 800 }, "email_alerts" : { "unlimited" : true , "used_this_month" : 3 } }
Show Response field reference
Number of farms currently owned by the user.
Farm limit for the plan. null for Pro/admin (unlimited).
true for Pro and admin users.
How many more farms the user can create. null for unlimited plans.
true when the user can still trigger AI analyses.
ai_analysis.max_tokens_per_analysis
Maximum output tokens the LLM may generate per single analysis — 800 on Free, 2048 on Pro.
Always true. Email alerts are unlimited on all plans.
email_alerts.used_this_month
Email alerts sent for this user’s farms in the current month.
PATCH /api/v1/users/{user_id}/plan Admin only. Promotes or demotes a user’s plan. Returns 403 for any non-admin caller.UUID of the target user. Returns 404 if the user does not exist.
Must be "free" or "paid". Any other value returns 422. When set to "paid", plan_activated_at is stamped with the current UTC timestamp.
Response — 200 OK — UserProfileResponse for the updated user.Example: curl -X PATCH https://surqo-api.fly.dev/api/v1/users/ < user-i d > /plan \ -H "Authorization: Bearer <admin-jwt>" \ -H "Content-Type: application/json" \ -d '{"plan": "paid"}'
Free vs Pro Plan Comparison Feature Free Pro Farms 1 Unlimited AI analyses 4 lifetime Unlimited Tokens per analysis 800 2,048 Email alerts Unlimited Unlimited Chat (token budget) 3,200 tokens Unlimited Priority support — ✓
Stripe integration is planned but not yet implemented. Plan upgrades are currently performed manually via the admin endpoint above.
