Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Codefied-CodePix/Karokar-backend/llms.txt

Use this file to discover all available pages before exploring further.

KaroKar exposes its business capabilities through a REST API built on NestJS. Every endpoint represents a business action rather than a raw database operation — a deliberate choice (per ADR-010) to keep internal domain models decoupled from external consumers. Whether you are building a corporate portal, a mobile application, or a partner integration, all interactions flow through this single API surface.

​
Base URL

The server reads its port from the PORT environment variable, defaulting to 3000. 
http://localhost:3000
For production deployments, replace localhost:3000 with your host. Routes are mounted at bare resource paths with no global prefix: 
http://localhost:3000/<resource>
API versioning is planned. ADR-010 states: “All APIs must be versioned. Breaking changes require a new version.” A URL prefix (e.g. /api/v1) is intended for a future release. The current codebase does not yet apply a global prefix — all routes are served at their bare paths (e.g. /bookings, /users).

​
Available Endpoints

The table below lists every route currently registered across the domain modules. Routes are grouped by the domain that owns them.

​
Identity

MethodPathDescription
POST/usersRegister a new user
GET/users/:idRetrieve a user by ID
POST/organizationsCreate a new organization
GET/organizations/:idRetrieve an organization by ID

​
Fleet

MethodPathDescription
POST/vehiclesAdd a vehicle to the fleet
GET/vehicles/searchSearch vehicles with filters
GET/vehicles/:idRetrieve a vehicle by ID
POST/vehicles/:id/maintenanceLog a maintenance event for a vehicle

​
Booking

MethodPathDescription
POST/bookingsCreate a new booking
GET/bookings/:idRetrieve a booking by ID
PATCH/bookings/:id/submitSubmit a draft booking for approval
PATCH/bookings/:id/approveApprove a submitted booking
PATCH/bookings/:id/rejectReject a submitted booking
PATCH/bookings/:id/assignAssign a driver to an approved booking
PATCH/bookings/:id/activateMark a booking as active (trip started)
PATCH/bookings/:id/completeComplete an active booking
PATCH/bookings/:id/cancelCancel a booking
PATCH/bookings/:id/terminateTerminate an active booking early

​
Assignment

MethodPathDescription
GET/assignments/:idRetrieve an assignment by ID
PATCH/assignments/:id/acceptDriver accepts an assignment

​
Administration

MethodPathDescription
POST/admin/organizations/:id/approvePlatform admin approves an organization
POST/admin/organizations/:id/rejectPlatform admin rejects an organization
POST/admin/organizations/:id/suspendPlatform admin suspends an organization

​
Request Format

All endpoints accept and return JSON. Set the Content-Type header on every write request: 
Content-Type: application/json

​
Input Validation

The application bootstraps a global ValidationPipe with the following configuration (from src/main.ts): 
app.useGlobalPipes(
  new ValidationPipe({
    whitelist: true,
    forbidNonWhitelisted: true,
    transform: true,
  }),
);
These three flags enforce strict input hygiene:
FlagBehaviour
whitelist: trueProperties not declared in the DTO class are silently stripped before the handler runs
forbidNonWhitelisted: trueIf a stripped property is detected, the request is rejected with 400 Bad Request instead of being silently discarded
transform: truePlain JSON values are automatically coerced into their declared DTO types (e.g. string "123" → number 123)
Sending unknown or extra fields in a request body will result in a 400 error. Ensure your payloads contain only the properties documented for each endpoint.

​
Error Response Format

KaroKar distinguishes between two categories of errors:

​
Domain Errors (400 Bad Request)

Business rule violations are raised as DomainException and caught by the global DomainExceptionFilter. The response shape is: 
{
  "statusCode": 400,
  "message": "A vehicle must be active before it can be booked.",
  "code": "VEHICLE_NOT_ACTIVE"
}
​
statusCode
number
required
Always 400 for domain errors.
​
message
string
required
A human-readable description of the business rule that was violated.
​
code
string
A machine-readable error code (e.g. BOOKING_NOT_FOUND). Present when the throwing code supplies one; omitted when no explicit code is provided (code?: string is optional on DomainException).

​
HTTP / Framework Errors

Errors from NestJS guards, pipes, or unhandled exceptions follow the standard NestJS error envelope: 
{
  "statusCode": 403,
  "message": "Forbidden resource",
  "error": "Forbidden"
}
Common HTTP status codes you will encounter:
CodeMeaning
400Validation failure or domain rule violation
401Missing or invalid JWT — userId or organizationId could not be resolved from the token
403Authenticated but lacking the required permission
404Resource not found
500Unexpected server error (includes unimplemented stubs such as AuthorizationService.can())

​
Multi-Tenant Design

KaroKar is a B2B2C platform where every resource belongs to an organization. ADR-010 mandates:
“Every API request must execute within organizational context.”
The OrganizationContextInterceptor runs on every request. It reads organizationId from the JWT payload and attaches it to request.organizationId. The PermissionGuard then uses both userId and organizationId when performing authorization checks.
Ensure your JWT payload always contains both userId (or sub) and organizationId. On any route protected with @RequirePermission, the guard will throw 401 Unauthorized if either claim cannot be resolved after the interceptor has run.

​
API Sections

Authentication

Learn how JWT tokens are validated and passed with every request. Understand the permission guard and organization context flow.

Users

Register users and retrieve user profiles within an organization context.

Organizations

Create and manage vendor or corporate organizations on the platform.

Vehicles

Add fleet vehicles, search available units, and log maintenance events.

Maintenance

Log and review maintenance events recorded against fleet vehicles.

Bookings

Manage the full booking lifecycle from creation through completion or termination.

Assignments

Retrieve and accept driver assignments linked to approved bookings.

Administration

Platform admin actions: approve, reject, or suspend organizations.

Build docs developers (and LLMs) love

Get started for freeTalk to us