API Reference Overview

Welcome to the Menon Mobility API documentation. Our REST API enables you to integrate with the platform programmatically for vehicle marketplace operations.

API Overview

The Menon Mobility API allows you to:

Listings: Create, read, update, and delete vehicle listings
Search: Query vehicles with advanced filters and faceted search
Categories & Brands: Access vehicle taxonomy data with specifications
Sellers: Retrieve seller profiles, listings, and reviews
Messages: Send and receive messages between buyers and sellers
Favorites & Comparisons: Manage user favorite lists and vehicle comparisons
Subscriptions: Manage subscription plans and billing
Notifications: Access user notifications and alerts
Webhooks: Receive real-time event notifications

Base URL

All API requests should be made to:

Production: https://api.menonmobility.com/v1
Sandbox:    https://sandbox-api.menonmobility.com/v1

For local development, the API runs at:

http://localhost:5001/api

Authentication

The API supports two authentication methods:

Method	Use Case	Header Format
JWT Token	User-authenticated requests	`Authorization: Bearer <jwt_token>`
API Key	Server-to-server integrations	`X-API-Key: <api_key>`

See Authentication for detailed setup instructions.

Quick Start

1. Get API Credentials

For JWT Authentication:

bash

POST /api/auth/login
Content-Type: application/json

{
  "email": "your@email.com",
  "password": "your_password"
}

For API Keys:

Go to Dashboard > Settings > API
Click "Generate API Key"
Copy your key (shown once)

2. Make Your First Request

bash

# List active vehicle listings
curl -X GET "https://api.menonmobility.com/api/listings" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"

3. Handle Response

json

{
  "success": true,
  "data": {
    "listings": [
      {
        "id": "clx1234567890",
        "title": "2022 Volvo FH 500 Euro 6",
        "slug": "2022-volvo-fh-500-euro-6",
        "price": 85000,
        "currency": "EUR",
        "year": 2022,
        "mileage": 180000,
        "status": "ACTIVE"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  }
}

API Endpoint Groups

Public Endpoints (No Auth Required)

Endpoint Group	Base Path	Description
Listings	`/api/listings`	Browse public listings
Search	`/api/search`	Search with filters
Categories	`/api/categories`	Category taxonomy
Brands	`/api/brands`	Brand and model data
Sellers	`/api/sellers/:slug`	Public seller profiles
Subscriptions	`/api/subscriptions/plans`	Available plans

Authenticated Endpoints (JWT Required)

Endpoint Group	Base Path	Description
Auth	`/api/auth`	Login, register, profile
Favorites	`/api/favorites`	Saved listings
Comparisons	`/api/comparisons`	Vehicle comparisons
Messages	`/api/messages`	Messaging system
Notifications	`/api/notifications`	User notifications

Seller Endpoints (SELLER Role Required)

Endpoint Group	Base Path	Description
Seller Dashboard	`/api/seller/dashboard`	Seller analytics
Seller Listings	`/api/seller/listings`	Manage listings
Bulk Import	`/api/seller/bulk-import`	CSV/XML import
Message Templates	`/api/seller/message-templates`	Quick responses
Team	`/api/seller/team`	Team management
Webhooks	`/api/seller/webhooks`	Event subscriptions

Admin Endpoints (ADMIN Role Required)

Endpoint Group	Base Path	Description
Admin Dashboard	`/api/admin/dashboard`	Platform stats
User Management	`/api/admin/users`	User CRUD
Listing Moderation	`/api/admin/listings`	Approve/reject
Category Admin	`/api/admin/categories`	Manage categories
Brand Admin	`/api/admin/brands`	Manage brands
Settings	`/api/admin/settings`	Platform config
Translations	`/api/admin/translations`	Language content

Response Format

Success Response

json

{
  "success": true,
  "data": {
    // Response payload
  },
  "message": "Optional success message"
}

Error Response

json

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "field": "price",
        "message": "Price must be a positive number"
      }
    ]
  }
}

Paginated Response

json

{
  "success": true,
  "data": {
    "items": [...],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8,
      "hasMore": true
    }
  }
}

HTTP Status Codes

Code	Description	Common Causes
200	Success	Request completed successfully
201	Created	Resource created successfully
204	No Content	Successful deletion
400	Bad Request	Invalid request body or parameters
401	Unauthorized	Missing or invalid authentication
403	Forbidden	Insufficient permissions
404	Not Found	Resource does not exist
409	Conflict	Resource already exists
422	Unprocessable	Validation error
429	Rate Limited	Too many requests
500	Server Error	Internal server error

Rate Limiting

API requests are rate-limited to ensure fair usage:

Endpoint Type	Limit	Window
Authentication	10 requests	15 minutes
Public Listings	60 requests	1 minute
Search	30 requests	1 minute
Seller Operations	120 requests	1 minute
File Uploads	20 requests	1 minute

Rate limit headers are included in all responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 55
X-RateLimit-Reset: 1642248000

Pagination

List endpoints support pagination with these parameters:

Parameter	Type	Description	Default
`page`	integer	Page number (1-based)	1
`limit`	integer	Items per page (max 100)	20
`sort`	string	Sort field	`createdAt`
`order`	string	Sort direction: `asc` or `desc`	`desc`

Example:

bash

GET /api/listings?page=2&limit=50&sort=price&order=asc

Filtering

Most list endpoints support filtering via query parameters:

bash

# Filter listings by multiple criteria
GET /api/listings?category=trucks&brand=volvo&minPrice=50000&maxPrice=100000&year=2020

# Search with text query
GET /api/search?q=volvo+fh+500&category=trucks

Caching

Many endpoints support caching:

Endpoint	Cache Duration
Categories	5 minutes
Brands	5 minutes
Single Listing	2 minutes
Listing List	1 minute
Search	1 minute
Search Suggestions	30 seconds

The Cache-Control header indicates cache duration for each response.

Versioning

The API is versioned via URL path:

Current version: v1 (implied in /api/ prefix)
Explicit version: /api/v1/ (for external API access)

We maintain backwards compatibility within major versions. Breaking changes will be announced with a deprecation period.

SDKs & Libraries

Official SDKs

JavaScript/Node.js: npm install @menonmobility/sdk
Python: pip install menonmobility
PHP: composer require menonmobility/sdk

JavaScript Example

javascript

const MenonMobility = require('@menonmobility/sdk');

const client = new MenonMobility({
  apiKey: process.env.MENON_API_KEY
});

// List trucks under EUR 100,000
const listings = await client.listings.list({
  category: 'trucks',
  maxPrice: 100000,
  limit: 10
});

// Search for Volvo vehicles
const results = await client.search({
  q: 'Volvo FH',
  category: 'trucks'
});

cURL Examples

bash

# Get all categories
curl -X GET "https://api.menonmobility.com/api/categories"

# Search listings
curl -X GET "https://api.menonmobility.com/api/search?q=volvo&category=trucks"

# Get single listing by slug
curl -X GET "https://api.menonmobility.com/api/listings/2022-volvo-fh-500"

Sandbox Environment

Test your integration without affecting production data:

https://sandbox-api.menonmobility.com/api

Sandbox features:

Isolated test environment
Test API keys (generate from sandbox dashboard)
No real transactions or payments
Reset data on demand
Full feature parity with production

Error Handling

Common Error Codes

Code	Description	Resolution
`INVALID_TOKEN`	JWT token is invalid	Re-authenticate
`TOKEN_EXPIRED`	JWT token has expired	Refresh token
`INVALID_API_KEY`	API key is invalid	Check key
`RATE_LIMITED`	Too many requests	Wait and retry
`VALIDATION_ERROR`	Invalid input data	Check request body
`NOT_FOUND`	Resource not found	Verify ID/slug
`FORBIDDEN`	Insufficient permissions	Check user role
`LISTING_LIMIT_EXCEEDED`	Plan limit reached	Upgrade plan

Retry Strategy

For transient errors (5xx, 429), implement exponential backoff:

javascript

async function fetchWithRetry(url, options, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      const response = await fetch(url, options);
      if (response.ok) return response.json();
      if (response.status === 429 || response.status >= 500) {
        await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000));
        continue;
      }
      throw new Error(`HTTP ${response.status}`);
    } catch (error) {
      if (i === retries - 1) throw error;
    }
  }
}

Support

Getting Help

Documentation: This API reference
Status Page: status.menonmobility.com
Technical Support: api-support@menonmobility.com
Developer Forum: community.menonmobility.com

Reporting Issues

When reporting API issues, include:

Request ID (from response headers if available)
Endpoint called (method + URL)
Request body (redact sensitive data)
Response received
Expected behavior
Timestamp of the request

Authentication - Setup API access
Listings - Create and manage listings
Search - Query vehicles
Webhooks - Real-time notifications

API Reference Overview ​

API Overview ​

Base URL ​

Authentication ​

Quick Start ​

1. Get API Credentials ​

2. Make Your First Request ​

3. Handle Response ​

API Endpoint Groups ​

Public Endpoints (No Auth Required) ​

Authenticated Endpoints (JWT Required) ​

Seller Endpoints (SELLER Role Required) ​

Admin Endpoints (ADMIN Role Required) ​

Response Format ​

Success Response ​

Error Response ​

Paginated Response ​

HTTP Status Codes ​

Rate Limiting ​

Pagination ​

Filtering ​

Caching ​

Versioning ​

SDKs & Libraries ​

Official SDKs ​

JavaScript Example ​

cURL Examples ​

Sandbox Environment ​

Error Handling ​

Common Error Codes ​

Retry Strategy ​

Support ​

Getting Help ​

Reporting Issues ​

Related Topics ​

API Reference Overview

API Overview

Base URL

Authentication

Quick Start

1. Get API Credentials

2. Make Your First Request

3. Handle Response

API Endpoint Groups

Public Endpoints (No Auth Required)

Authenticated Endpoints (JWT Required)

Seller Endpoints (SELLER Role Required)

Admin Endpoints (ADMIN Role Required)

Response Format

Success Response

Error Response

Paginated Response

HTTP Status Codes

Rate Limiting

Pagination

Filtering

Caching

Versioning

SDKs & Libraries

Official SDKs

JavaScript Example

cURL Examples

Sandbox Environment

Error Handling

Common Error Codes

Retry Strategy

Support

Getting Help

Reporting Issues

Related Topics