# MechZie API

> Internal API documentation for the MechZie roadside mechanic dispatch service

## Docs

- [Create service category (admin)](https://internal.mechzie.in/docs/api-reference/admin/create-service-category-admin.md)
- [Delete service category (admin)](https://internal.mechzie.in/docs/api-reference/admin/delete-service-category-admin.md)
- [Get admin dashboard stats](https://internal.mechzie.in/docs/api-reference/admin/get-admin-dashboard-stats.md)
- [Get job detail](https://internal.mechzie.in/docs/api-reference/admin/get-job-detail.md)
- [Get mechanic documents](https://internal.mechzie.in/docs/api-reference/admin/get-mechanic-documents.md)
- [Initiate refund](https://internal.mechzie.in/docs/api-reference/admin/initiate-refund.md)
- [List all jobs](https://internal.mechzie.in/docs/api-reference/admin/list-all-jobs.md)
- [List all mechanics](https://internal.mechzie.in/docs/api-reference/admin/list-all-mechanics.md)
- [List all service categories (admin)](https://internal.mechzie.in/docs/api-reference/admin/list-all-service-categories-admin.md)
- [List all users](https://internal.mechzie.in/docs/api-reference/admin/list-all-users.md)
- [Review document](https://internal.mechzie.in/docs/api-reference/admin/review-document.md)
- [Update service category (admin)](https://internal.mechzie.in/docs/api-reference/admin/update-service-category-admin.md)
- [Verify/reject mechanic](https://internal.mechzie.in/docs/api-reference/admin/verifyreject-mechanic.md)
- [Complete admin account setup via invite token](https://internal.mechzie.in/docs/api-reference/auth/complete-admin-account-setup-via-invite-token.md): Accepts an email-based admin invite. The caller supplies a Firebase ID token (to prove phone/email ownership) and the opaque invite token received by email. Rate-limited separately from the regular OTP flow.
- [Exchange Firebase ID token for JWT pair](https://internal.mechzie.in/docs/api-reference/auth/exchange-firebase-id-token-for-jwt-pair.md)
- [Revoke refresh token](https://internal.mechzie.in/docs/api-reference/auth/revoke-refresh-token.md)
- [Rotate refresh token and get new access token](https://internal.mechzie.in/docs/api-reference/auth/rotate-refresh-token-and-get-new-access-token.md)
- [Accept an incoming call (exchange nonce for HMS token)](https://internal.mechzie.in/docs/api-reference/call/accept-an-incoming-call-exchange-nonce-for-hms-token.md): Receiver taps "Accept" — exchanges the single-use nonce (received via FCM) for a fresh HMS auth token, transitions Redis state from ringing to active, and cancels the BullMQ timeout job.
- [Cancel an outgoing call before answered](https://internal.mechzie.in/docs/api-reference/call/cancel-an-outgoing-call-before-answered.md): Caller taps "Cancel" before the receiver answers — cleans up Redis, cancels BullMQ timeout, sends a `call_cancelled` FCM to dismiss the receiver's native call UI.
- [Decline an incoming call](https://internal.mechzie.in/docs/api-reference/call/decline-an-incoming-call.md): Receiver taps "Decline" — cleans up Redis ringing state, cancels the BullMQ timeout, and emits `call:declined` to the caller via Socket.io.
- [End an active call (hangup)](https://internal.mechzie.in/docs/api-reference/call/end-an-active-call-hangup.md): Either party hangs up — clears the `call:active:{jobId}` Redis key so a new call can be initiated. Emits `call:ended` Socket.io event to both parties. **Idempotent**: returns 200 even if no active call exists (e.g. TTL expired or already ended).
- [Initiate a call (ring the other party)](https://internal.mechzie.in/docs/api-reference/call/initiate-a-call-ring-the-other-party.md): Caller taps "Call" — creates/reuses the 100ms room, sends a data-only FCM push to the other party, schedules a 30 s timeout, and returns an HMS auth token so the caller can join the room immediately.
- [Get chat history for a job (paginated, oldest-first)](https://internal.mechzie.in/docs/api-reference/comms/get-chat-history-for-a-job-paginated-oldest-first.md): Returns persisted chat messages. Use the `before` cursor for backward pagination. Primary chat delivery is via Socket.IO `chat:message` events; this endpoint serves history on load and as a REST fallback.
- [Get or create a 100ms audio call room and return an auth token](https://internal.mechzie.in/docs/api-reference/comms/get-or-create-a-100ms-audio-call-room-and-return-an-auth-token.md): Idempotent. Creates a 100ms room on first call and persists the room ID to the job record. Subsequent calls reuse the same room. Returns a short-lived auth token scoped to the caller's role (`customer` or `mechanic`).
- [Send a chat message (REST fallback)](https://internal.mechzie.in/docs/api-reference/comms/send-a-chat-message-rest-fallback.md): Persists a chat message to the database and broadcasts it to the job room via Socket.IO. Prefer the `chat:send` Socket.IO event for lower latency; use this endpoint when WebSocket is unavailable.
- [Liveness check](https://internal.mechzie.in/docs/api-reference/health/liveness-check.md)
- [Readiness check with DB and Redis probes](https://internal.mechzie.in/docs/api-reference/health/readiness-check-with-db-and-redis-probes.md)
- [Add line item (mechanic only)](https://internal.mechzie.in/docs/api-reference/jobs/add-line-item-mechanic-only.md)
- [Admin resolves a disputed job](https://internal.mechzie.in/docs/api-reference/jobs/admin-resolves-a-disputed-job.md): Transitions job from `disputed` → `resolved` (terminal state). Admin only. Triggers 100ms room destruction and starts the 30-day chat retention clock.
- [Cancel job](https://internal.mechzie.in/docs/api-reference/jobs/cancel-job.md)
- [Create job and trigger dispatch (customer only)](https://internal.mechzie.in/docs/api-reference/jobs/create-job-and-trigger-dispatch-customer-only.md)
- [Customer or admin disputes a completed job](https://internal.mechzie.in/docs/api-reference/jobs/customer-or-admin-disputes-a-completed-job.md): Transitions job from `completed` → `disputed`. Only accessible by the customer who owns the job, or an admin. Opens a dispute resolution window where communication remains active.
- [Get job details](https://internal.mechzie.in/docs/api-reference/jobs/get-job-details.md)
- [List line items for a job](https://internal.mechzie.in/docs/api-reference/jobs/list-line-items-for-a-job.md)
- [List own jobs (paginated)](https://internal.mechzie.in/docs/api-reference/jobs/list-own-jobs-paginated.md)
- [Mechanic accepts job offer](https://internal.mechzie.in/docs/api-reference/jobs/mechanic-accepts-job-offer.md)
- [Mechanic declines job offer](https://internal.mechzie.in/docs/api-reference/jobs/mechanic-declines-job-offer.md)
- [Mechanic marks arrived](https://internal.mechzie.in/docs/api-reference/jobs/mechanic-marks-arrived.md)
- [Mechanic marks en route](https://internal.mechzie.in/docs/api-reference/jobs/mechanic-marks-en-route.md)
- [Mechanic marks job complete](https://internal.mechzie.in/docs/api-reference/jobs/mechanic-marks-job-complete.md)
- [Mechanic marks work started](https://internal.mechzie.in/docs/api-reference/jobs/mechanic-marks-work-started.md)
- [Remove line item (mechanic only)](https://internal.mechzie.in/docs/api-reference/jobs/remove-line-item-mechanic-only.md)
- [Get mechanic statistics](https://internal.mechzie.in/docs/api-reference/mechanics/get-mechanic-statistics.md)
- [Get own mechanic profile](https://internal.mechzie.in/docs/api-reference/mechanics/get-own-mechanic-profile.md)
- [List own uploaded documents](https://internal.mechzie.in/docs/api-reference/mechanics/list-own-uploaded-documents.md)
- [Submit mechanic profile for verification](https://internal.mechzie.in/docs/api-reference/mechanics/submit-mechanic-profile-for-verification.md)
- [Toggle online/offline status](https://internal.mechzie.in/docs/api-reference/mechanics/toggle-onlineoffline-status.md)
- [Update mechanic location (HTTP fallback)](https://internal.mechzie.in/docs/api-reference/mechanics/update-mechanic-location-http-fallback.md)
- [List notifications (paginated)](https://internal.mechzie.in/docs/api-reference/notifications/list-notifications-paginated.md)
- [Mark all notifications as read](https://internal.mechzie.in/docs/api-reference/notifications/mark-all-notifications-as-read.md)
- [Mark single notification as read](https://internal.mechzie.in/docs/api-reference/notifications/mark-single-notification-as-read.md)
- [Register/update FCM push token](https://internal.mechzie.in/docs/api-reference/notifications/registerupdate-fcm-push-token.md)
- [Check for outstanding cancellation fees](https://internal.mechzie.in/docs/api-reference/payments/check-for-outstanding-cancellation-fees.md): Returns cancelled jobs where the customer still owes a cancellation fee (cancellation_fee > 0). Use this to show a payment prompt before the customer can create a new job.
- [Check for outstanding cancellation fees (alias)](https://internal.mechzie.in/docs/api-reference/payments/check-for-outstanding-cancellation-fees-alias.md): Alias for /payments/unpaid-fees. Returns the same response. Prefer /payments/unpaid-fees for new integrations; this path is kept for backward compatibility.
- [Create Razorpay order (customer only)](https://internal.mechzie.in/docs/api-reference/payments/create-razorpay-order-customer-only.md)
- [Get payment status for a job](https://internal.mechzie.in/docs/api-reference/payments/get-payment-status-for-a-job.md)
- [Razorpay webhook (no auth)](https://internal.mechzie.in/docs/api-reference/payments/razorpay-webhook-no-auth.md): Receives Razorpay event notifications. Requires the `X-Razorpay-Signature` header for HMAC-SHA256 body verification. Returns `200` even on business-logic errors to prevent Razorpay from retrying. Returns `400` when the request body is missing or cannot be parsed.
- [Verify Razorpay signature (optimistic UI)](https://internal.mechzie.in/docs/api-reference/payments/verify-razorpay-signature-optimistic-ui.md)
- [Get both ratings for a job](https://internal.mechzie.in/docs/api-reference/ratings/get-both-ratings-for-a-job.md)
- [Get mechanic ratings](https://internal.mechzie.in/docs/api-reference/ratings/get-mechanic-ratings.md)
- [Submit a rating](https://internal.mechzie.in/docs/api-reference/ratings/submit-a-rating.md)
- [Create new category (admin only)](https://internal.mechzie.in/docs/api-reference/service-categories/create-new-category-admin-only.md)
- [Delete category (admin only)](https://internal.mechzie.in/docs/api-reference/service-categories/delete-category-admin-only.md)
- [Get specific category](https://internal.mechzie.in/docs/api-reference/service-categories/get-specific-category.md)
- [List categories (filter by vehicle type)](https://internal.mechzie.in/docs/api-reference/service-categories/list-categories-filter-by-vehicle-type.md)
- [Update category (admin only)](https://internal.mechzie.in/docs/api-reference/service-categories/update-category-admin-only.md)
- [Create an admin invite](https://internal.mechzie.in/docs/api-reference/super-admin/create-an-admin-invite.md): Generates a time-limited invite token and sends it to the target email. Only super_admin users may call this endpoint.
- [Revoke a pending admin invite](https://internal.mechzie.in/docs/api-reference/super-admin/revoke-a-pending-admin-invite.md): Invalidates the invite token so it can no longer be used. Only super_admin users may call this.
- [Update a user's role](https://internal.mechzie.in/docs/api-reference/super-admin/update-a-users-role.md): Promotes or demotes any user to a different role. Only super_admin users may call this endpoint.
- [Get job tracking info (HTTP polling fallback)](https://internal.mechzie.in/docs/api-reference/tracking/get-job-tracking-info-http-polling-fallback.md)
- [Generate S3 presigned upload URL](https://internal.mechzie.in/docs/api-reference/uploads/generate-s3-presigned-upload-url.md)
- [Get current user profile](https://internal.mechzie.in/docs/api-reference/users/get-current-user-profile.md)
- [Get user by ID (admin only)](https://internal.mechzie.in/docs/api-reference/users/get-user-by-id-admin-only.md)
- [Update current user profile](https://internal.mechzie.in/docs/api-reference/users/update-current-user-profile.md)
- [Add new vehicle](https://internal.mechzie.in/docs/api-reference/vehicles/add-new-vehicle.md)
- [Delete vehicle](https://internal.mechzie.in/docs/api-reference/vehicles/delete-vehicle.md)
- [Get specific vehicle](https://internal.mechzie.in/docs/api-reference/vehicles/get-specific-vehicle.md)
- [List own vehicles](https://internal.mechzie.in/docs/api-reference/vehicles/list-own-vehicles.md)
- [Update vehicle](https://internal.mechzie.in/docs/api-reference/vehicles/update-vehicle.md)
- [Add and verify a UPI account](https://internal.mechzie.in/docs/api-reference/wallet/add-and-verify-a-upi-account.md): Creates a RazorpayX contact + fund account and triggers VPA validation. Verification is asynchronous.
- [Admin approve UPI account](https://internal.mechzie.in/docs/api-reference/wallet/admin-approve-upi-account.md): Manually approve a UPI account that failed automatic VPA name matching.
- [Get disputes for a job](https://internal.mechzie.in/docs/api-reference/wallet/get-disputes-for-a-job.md)
- [Get wallet balance summary](https://internal.mechzie.in/docs/api-reference/wallet/get-wallet-balance-summary.md): Returns pending, available, and locked balances for the authenticated mechanic.
- [Initiate a refund (admin)](https://internal.mechzie.in/docs/api-reference/wallet/initiate-a-refund-admin.md): Issues a refund via Razorpay API, creates clawback ledger entries, and deducts from mechanic wallet.
- [List payout history](https://internal.mechzie.in/docs/api-reference/wallet/list-payout-history.md): Paginated payout history for the authenticated mechanic.
- [List refunds for a payment](https://internal.mechzie.in/docs/api-reference/wallet/list-refunds-for-a-payment.md)
- [List UPI accounts](https://internal.mechzie.in/docs/api-reference/wallet/list-upi-accounts.md): Returns all UPI accounts for the authenticated mechanic with verification status.
- [List wallet transactions](https://internal.mechzie.in/docs/api-reference/wallet/list-wallet-transactions.md): Paginated transaction history for the authenticated mechanic.
- [Raise a dispute](https://internal.mechzie.in/docs/api-reference/wallet/raise-a-dispute.md): Creates a dispute on a completed/paid job. Freezes the mechanic's pending earnings.
- [Resolve a dispute (admin)](https://internal.mechzie.in/docs/api-reference/wallet/resolve-a-dispute-admin.md): Admin resolves a dispute. Resolution options: - `resolved_customer`: Refund issued, mechanic loses frozen earnings - `resolved_mechanic`: Frozen earnings released to mechanic - `rejected`: Same as resolved_mechanic (dispute was invalid)
- [Authentication](https://internal.mechzie.in/docs/authentication.md): Firebase OTP → JWT token exchange, refresh flow, and token management for MechZie
- [Local Development](https://internal.mechzie.in/docs/development.md): Set up and run the MechZie API locally
- [Error Handling](https://internal.mechzie.in/docs/error-handling.md): Error codes, rate limiting, pagination, and response format reference
- [File Uploads](https://internal.mechzie.in/docs/file-uploads.md): S3 presigned URL flow for uploading images and documents
- [MechZie API Documentation](https://internal.mechzie.in/docs/index.md): Internal API docs for the MechZie roadside mechanic dispatch service — for frontend devs and AI-assisted development
- [Job Lifecycle](https://internal.mechzie.in/docs/job-lifecycle.md): Job state machine, status transitions, dispatch system, and cancellation rules
- [Notifications](https://internal.mechzie.in/docs/notifications.md): FCM push notifications, in-app notification management, and notification triggers
- [Payments](https://internal.mechzie.in/docs/payments.md): Razorpay integration, double-entry ledger, commission splits, webhook processing, and cancellation fees
- [Quickstart](https://internal.mechzie.in/docs/quickstart.md): Make your first API call to MechZie in 5 minutes
- [Real-time Events](https://internal.mechzie.in/docs/realtime.md): Socket.io connection, authentication, rooms, and event reference for live tracking and dispatch
- [Voice Calls](https://internal.mechzie.in/docs/voice-calls.md): In-job audio calls using 100ms rooms with FCM signaling — ringing, accept, decline, cancel, end, and missed-call handling
- [Wallet & Settlements](https://internal.mechzie.in/docs/wallet-settlements.md): Mechanic wallet, UPI verification, disputes, refunds, payouts, and settlement cycles

## OpenAPI Specs

- [openapi](https://internal.mechzie.in/docs/openapi.yaml)

## Optional

- [GitHub](https://github.com/MechZie)