Skip to main content

​
MaqAgr API

MaqAgr is a robust REST API designed for comprehensive agricultural machinery management. It enables you to manage inventories of tractors and implements, characterize terrains, and perform complex engineering calculations (power losses, machinery recommendations) based on applied physics.

Quick Start

Get up and running with MaqAgr API in minutes

Authentication

Learn how to authenticate using JWT tokens

API Reference

Explore all available endpoints and operations

Examples

View practical examples and use cases

​
Key Features

Tractor Management

Complete inventory system for tractors with power, weight, brand, and model specifications

Implement Tracking

Manage agricultural implements with type, weight, and working width data

Terrain Characterization

Define terrain properties including soil type, slope, altitude, and area

Power Calculations

Calculate net power accounting for altitude, slope, and rolling resistance losses

Smart Recommendations

AI-powered algorithm suggests the best tractor for specific tasks

Engineering Physics

Implements academic formulas for agricultural efficiency calculations

​
Technology Stack

MaqAgr API is built with modern, production-ready technologies:
  • Runtime: Node.js v24.13.0+
  • Framework: Express 5.2.1
  • Database: PostgreSQL 12+
  • Authentication: JWT (JSON Web Tokens)
  • Security: Helmet, CORS, XSS protection, rate limiting
  • Logging: Winston with daily rotation
  • Cache: Redis (ioredis)
  • Testing: Jest with 97+ tests (unit + E2E)

​
API Response Format

All API responses follow the JSend standard for consistency:

​
Success Response

{
  "success": true,
  "message": "Operation description",
  "data": { ... }
}

​
Error Response

{
  "success": false,
  "message": "Error description"
}
In development mode, error responses include additional debugging information such as stack traces and error codes.

​
Paginated Response

For endpoints that return lists, pagination metadata is included: 
{
  "success": true,
  "message": "Data retrieved",
  "data": [...],
  "pagination": {
    "currentPage": 1,
    "totalPages": 5,
    "pageSize": 10,
    "totalItems": 50,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}

​
HTTP Status Codes

The API uses standard HTTP status codes:
CodeDescriptionUsage
200OKSuccessful operation
201CreatedResource created successfully
204No ContentSuccessful operation with no content
400Bad RequestValidation error or invalid data
401UnauthorizedAuthentication required or invalid token
403ForbiddenNo permission to access resource
404Not FoundResource not found
409ConflictConflict (e.g., email already registered)
500Internal Server ErrorServer error

​
Core Endpoints

The API provides the following main resource groups:

Authentication

/api/authUser registration, login, and profile management

Tractors

/api/tractorsCRUD operations for tractor inventory

Implements

/api/implementsManage agricultural implements and attachments

Terrains

/api/terrainsCreate and manage terrain profiles

Calculations

/api/calculationsPower loss and minimum power calculations

Recommendations

/api/recommendationsGet intelligent tractor recommendations

​
Base URL

When running locally, the API is available at: 
http://localhost:4000
The default port is 4000, but this can be configured via the PORT environment variable.

​
Getting Help

If you encounter issues or have questions:
  • Check the Quick Start guide for setup instructions
  • Review the Authentication documentation
  • Explore the API Reference for detailed endpoint information
  • Examine response error messages - they include helpful validation details

​
Next Steps

Get Started

Follow the quick start guide to install and configure the API

Authentication Guide

Learn how to authenticate and secure your API requests

Build docs developers (and LLMs) love

Get started for freeTalk to us