{"openapi":"3.0.3","info":{"title":"TruckerGuard API","version":"0.1.0","description":"Backend API for TruckerGuard AI. Responses use `{ data }` on success and `{ error, code? }` on failure."},"servers":[{"url":"http://localhost:3000","description":"Local dev"},{"url":"/","description":"Current host (relative)"}],"tags":[{"name":"System","description":"Health and metadata"},{"name":"Signup","description":"Marketing signup (no auth)"},{"name":"Billing","description":"Stripe checkout (company admin)"},{"name":"Account","description":"Authenticated user session"},{"name":"AI","description":"Claude analysis jobs"},{"name":"Superadmin","description":"Platform billing only"},{"name":"Webhooks","description":"Stripe and integrations"},{"name":"Cron","description":"Scheduled jobs (server secret)"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Supabase access token (JWT includes company_id after auth hook)"},"cronSecret":{"type":"apiKey","in":"header","name":"x-cron-secret"},"smartptiSecret":{"type":"apiKey","in":"header","name":"x-smartpti-secret"},"stripeSignature":{"type":"apiKey","in":"header","name":"stripe-signature","description":"Stripe webhook signing header"}},"schemas":{"ErrorResponse":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error"]},"HealthData":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"service":{"type":"string","example":"truckerguard-api"},"timestamp":{"type":"string","format":"date-time"}}},"SignupRegisterRequest":{"type":"object","required":["email","companyName","planTier"],"properties":{"email":{"type":"string","format":"email"},"companyName":{"type":"string","minLength":2,"maxLength":200},"planTier":{"type":"string","enum":["starter","professional","enterprise"]},"sellerId":{"type":"string","format":"uuid"},"utmSource":{"type":"string"},"utmCampaign":{"type":"string"}}},"SignupRegisterData":{"type":"object","properties":{"signupIntentId":{"type":"string","format":"uuid"},"companyId":{"type":"string","format":"uuid"},"trialEndsAt":{"type":"string","format":"date-time"},"message":{"type":"string"}}},"CompanyIdBody":{"type":"object","required":["companyId"],"properties":{"companyId":{"type":"string","format":"uuid"}}},"CheckoutData":{"type":"object","properties":{"checkoutUrl":{"type":"string","format":"uri","nullable":true},"sessionId":{"type":"string"}}},"ActiveCompanyData":{"type":"object","properties":{"activeCompanyId":{"type":"string","format":"uuid"},"message":{"type":"string"}}},"AiJobCreateRequest":{"type":"object","required":["companyId","jobType"],"properties":{"companyId":{"type":"string","format":"uuid"},"jobType":{"type":"string","enum":["insurance_policy_parse","insurance_compliance_check","bol_scan","inspection_analyze","cargo_coverage_verify","driver_risk_score","csa_prediction"]},"inputText":{"type":"string"},"inputStoragePath":{"type":"string"},"relatedEntityType":{"type":"string"},"relatedEntityId":{"type":"string","format":"uuid"},"runImmediately":{"type":"boolean"}}},"SmartptiPayload":{"type":"object","required":["companyId","deviceSerial","truckId","passed","inspectedAt"],"properties":{"companyId":{"type":"string","format":"uuid"},"deviceSerial":{"type":"string"},"truckId":{"type":"string","format":"uuid"},"passed":{"type":"boolean"},"inspectedAt":{"type":"string","format":"date-time"},"rawPayload":{"type":"object","additionalProperties":true}}}}},"paths":{"/api/v1/health":{"get":{"tags":["System"],"summary":"Health check","operationId":"getHealth","responses":{"200":{"description":"Service is up","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/HealthData"}}}}}}}}},"/api/v1/signup/register":{"post":{"tags":["Signup"],"summary":"Register company with 14-day trial (no card)","operationId":"postSignupRegister","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupRegisterRequest"}}}},"responses":{"201":{"description":"Company provisioned","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SignupRegisterData"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Provisioning failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/billing/create-checkout":{"post":{"tags":["Billing"],"summary":"Create Stripe Checkout session (after trial)","operationId":"postBillingCreateCheckout","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyIdBody"}}}},"responses":{"200":{"description":"Checkout session created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CheckoutData"}}}}}},"400":{"description":"Invalid body"},"401":{"description":"Unauthorized"},"403":{"description":"Wrong company or role"},"404":{"description":"Subscription not found"}}}},"/api/v1/me/active-company":{"patch":{"tags":["Account"],"summary":"Set active company for JWT company_id claim","operationId":"patchMeActiveCompany","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyIdBody"}}}},"responses":{"200":{"description":"Active company updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ActiveCompanyData"}}}}}},"400":{"description":"Invalid body"},"401":{"description":"Unauthorized"},"403":{"description":"Not a member of company"}}}},"/api/v1/ai/jobs":{"post":{"tags":["AI"],"summary":"Create (and optionally run) an AI analysis job","operationId":"postAiJobs","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiJobCreateRequest"}}}},"responses":{"201":{"description":"Job created"},"400":{"description":"Invalid body"},"401":{"description":"Unauthorized"},"403":{"description":"Company context mismatch"},"500":{"description":"Job creation failed"}}}},"/api/v1/superadmin/billing":{"get":{"tags":["Superadmin"],"summary":"Billing dashboard (MRR + companies, no ops data)","operationId":"getSuperadminBilling","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Billing aggregates","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"companies":{"type":"array","items":{"type":"object"}},"mrrByPlan":{"type":"array","items":{"type":"object"}}}}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Not superadmin"}}}},"/api/v1/webhooks/stripe":{"post":{"tags":["Webhooks"],"summary":"Stripe webhook handler","operationId":"postWebhooksStripe","security":[{"stripeSignature":[]}],"description":"Raw JSON body; verified with STRIPE_WEBHOOK_SECRET.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Stripe event payload"}}}},"responses":{"200":{"description":"Event processed or skipped"},"400":{"description":"Invalid signature or payload"}}}},"/api/v1/cron/trial-expiry":{"post":{"tags":["Cron"],"summary":"Mark expired trials as past_due","operationId":"postCronTrialExpiry","security":[{"cronSecret":[]}],"responses":{"200":{"description":"Cron run result"},"401":{"description":"Invalid or missing x-cron-secret"}}}},"/api/v1/integrations/smartpti":{"post":{"tags":["Webhooks"],"summary":"Ingest SmartPTI inspection","operationId":"postIntegrationsSmartpti","security":[{"smartptiSecret":[]}],"description":"If SMARTPTI_WEBHOOK_SECRET is unset, requests are accepted (dev only).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmartptiPayload"}}}},"responses":{"201":{"description":"Inspection recorded"},"400":{"description":"Invalid payload"},"401":{"description":"Invalid x-smartpti-secret"}}}}}}