{"openapi":"3.1.0","info":{"title":"Blucollarz API","version":"1.0.0","description":"External REST API for candidate pipeline status. MCP tools mirror these read endpoints at /api/mcp."},"servers":[{"url":"/"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key created in Admin → Settings → API Keys (blz_live_…)."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"GateStatus":{"type":"object","properties":{"complete":{"type":"boolean"},"kycVerified":{"type":"boolean"},"selected":{"type":"boolean"}},"required":["complete","kycVerified","selected"]},"Progress":{"type":"object","description":"Candidate dashboard: applications, stats, medical appointments.","additionalProperties":true},"PhoneLookup":{"type":"object","properties":{"userId":{"type":"string"},"phoneCountryCode":{"type":"integer"},"phoneNumber":{"type":"integer"}},"required":["userId","phoneCountryCode","phoneNumber"]}}},"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"paths":{"/api/health":{"get":{"summary":"Health check","security":[],"responses":{"200":{"description":"Service is up","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"service":{"type":"string"}}}}}}}}},"/api/v1/candidates/{userId}/gate-status":{"get":{"summary":"Candidate onboarding gate status","parameters":[{"name":"userId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Gate flags for profile, KYC, and selected application","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GateStatus"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Candidate not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/candidates/by-phone/lookup":{"get":{"summary":"Resolve candidate userId from phone (WhatsApp)","parameters":[{"name":"phone","in":"query","required":true,"schema":{"type":"string"},"description":"9876543210, 919876543210, or +919876543210"},{"name":"countryCode","in":"query","required":false,"schema":{"type":"string"},"description":"Optional dial code when phone is national digits"}],"responses":{"200":{"description":"Candidate user id for the phone number","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneLookup"}}}},"404":{"description":"Candidate not found"},"409":{"description":"Multiple candidates share this phone"}}}},"/api/v1/candidates/by-phone/gate-status":{"get":{"summary":"Gate status by phone","parameters":[{"name":"phone","in":"query","required":true,"schema":{"type":"string"}},{"name":"countryCode","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GateStatus"}}}}}}},"/api/v1/candidates/by-phone/progress":{"get":{"summary":"Pipeline progress by phone","parameters":[{"name":"phone","in":"query","required":true,"schema":{"type":"string"}},{"name":"countryCode","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Progress"}}}}}}},"/api/v1/candidates/{userId}/progress":{"get":{"summary":"Candidate pipeline progress","description":"Applications, interview stages, medical status, and aggregate stats.","parameters":[{"name":"userId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Dashboard-style progress payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Progress"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Candidate not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"x-mcp":{"endpoint":"/api/mcp","transport":"streamable-http","tools":[{"name":"resolve_candidate_by_phone","description":"Resolve candidate userId from WhatsApp phone number","restEquivalent":"GET /api/v1/candidates/by-phone/lookup?phone=…"},{"name":"get_candidate_gate_status","description":"Read profile/KYC/selection gate flags (userId or phone)","restEquivalent":"GET /api/v1/candidates/{userId}/gate-status or by-phone/gate-status"},{"name":"get_candidate_progress","description":"Read applications, interviews, medical, stats (userId or phone)","restEquivalent":"GET /api/v1/candidates/{userId}/progress or by-phone/progress"}]}}