> ## Documentation Index
> Fetch the complete documentation index at: https://internal.mechzie.in/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Make your first API call to MechZie in 5 minutes

## Prerequisites

Before starting, make sure you have:

* A Firebase project with **Phone Authentication** enabled
* The MechZie API base URL
* `socket_io_client` and `razorpay_flutter` packages in your Flutter project

### API Environments

<CardGroup cols={2}>
  <Card title="Production" icon="globe">
    ```
    https://mechzie-api-production.run.app/api/v1
    ```
  </Card>

  <Card title="Local Development" icon="laptop">
    ```
    http://localhost:3000/api/v1
    ```
  </Card>
</CardGroup>

### Client SDK Dependencies

```yaml theme={null}
# pubspec.yaml
dependencies:
  firebase_auth: ^5.0.0
  socket_io_client: ^3.0.0
  razorpay_flutter: ^1.3.0
  flutter_secure_storage: ^9.0.0
```

## Authenticate and Make Your First Call

<Steps>
  <Step title="Sign in with Firebase Phone OTP">
    Use the Firebase Auth SDK to verify the user's phone number. This happens entirely client-side — the MechZie API is not involved yet.

    ```dart theme={null}
    await FirebaseAuth.instance.verifyPhoneNumber(
      phoneNumber: '+919876543210',
      codeSent: (verificationId, _) {
        // Store verificationId, then verify the OTP code:
        final credential = PhoneAuthProvider.credential(
          verificationId: verificationId,
          smsCode: userEnteredCode,
        );
        final result = await FirebaseAuth.instance.signInWithCredential(credential);
        final firebaseIdToken = await result.user!.getIdToken();
      },
      verificationCompleted: (_) {},
      verificationFailed: (e) => print(e),
      codeAutoRetrievalTimeout: (_) {},
    );
    ```
  </Step>

  <Step title="Exchange Firebase token for MechZie JWT">
    Send the Firebase ID token to get your access and refresh tokens:

    ```bash theme={null}
    curl -X POST http://localhost:3000/api/v1/auth/verify-otp \
      -H "Content-Type: application/json" \
      -d '{
        "firebaseIdToken": "eyJhbGciOiJSUzI1NiIs...",
        "role": "customer"
      }'
    ```

    **Response:**

    ```json theme={null}
    {
      "accessToken": "eyJhbGciOiJIUzI1NiIs...",
      "refreshToken": "a1b2c3d4e5f6...",
      "user": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "phone": "+919876543210",
        "name": null,
        "role": "customer"
      }
    }
    ```

    <Tip>
      The access token expires in **15 minutes**. The refresh token is valid for **30 days**. See [Authentication](/authentication) for the full refresh flow.
    </Tip>
  </Step>

  <Step title="Fetch your profile">
    Use the access token to make authenticated requests:

    ```bash theme={null}
    curl -X GET http://localhost:3000/api/v1/users/me \
      -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
    ```

    **Response:**

    ```json theme={null}
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "phone": "+919876543210",
      "name": null,
      "email": null,
      "role": "customer",
      "avatar_url": null,
      "created_at": "2026-05-21T10:00:00.000Z",
      "updated_at": "2026-05-21T10:00:00.000Z"
    }
    ```

    <Check>
      If you get your user profile back, you're authenticated and ready to go!
    </Check>
  </Step>
</Steps>

## Create Your First Job

```bash theme={null}
curl -X POST http://localhost:3000/api/v1/jobs \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "service_category_id": "uuid-of-service-category",
    "pickup_address": "MG Road, Bangalore, Karnataka",
    "pickup_lat": 12.9716,
    "pickup_lng": 77.5946,
    "description": "Flat tire, need roadside help"
  }'
```

<Note>
  To get valid `service_category_id` values, first call `GET /api/v1/service-categories`. Optionally include `vehicle_id` (from `GET /api/v1/vehicles`) and `photo_urls` (from [File Uploads](/file-uploads)).
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="shield" href="/authentication">
    Token refresh, logout, admin invite flow
  </Card>

  <Card title="Real-time Events" icon="bolt" href="/realtime">
    Socket.io connection, live tracking, dispatch events
  </Card>

  <Card title="Job Lifecycle" icon="clipboard-list" href="/job-lifecycle">
    State machine, dispatch tiers, cancellation rules
  </Card>

  <Card title="Payments" icon="credit-card" href="/payments">
    Razorpay checkout, webhook, cancellation fees
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/error-handling">
    Error codes, rate limits, pagination
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference">
    All 56 REST endpoints with interactive examples
  </Card>
</CardGroup>

<Warning>
  Always use HTTPS in production. Store tokens in secure storage (e.g., `flutter_secure_storage`), never in SharedPreferences.
</Warning>