Skip to main content

​
Create Tractor

Create a new tractor in the catalog. This endpoint requires administrator authentication.
Admin Access Required - This endpoint requires a valid JWT token with role_id: 1 (administrator).

​
Endpoint

POST /api/tractors

​
Authentication

This endpoint requires both authentication and administrator privileges: 
Authorization: Bearer <jwt_token>
See the Authentication guide for details on obtaining and using JWT tokens.

​
Request Body

​
brand
string
required
Tractor brand/manufacturer name. Cannot be empty.Example: "John Deere", "Case IH", "New Holland"
​
model
string
required
Tractor model identifier. Cannot be empty.Example: "6130M", "Magnum 280", "T7.315"
​
engine_power_hp
number
required
Engine power in horsepower (HP). Must be a positive number.Example: 130, 280, 315.5
​
traction_type
string
required
Type of traction system. Must be one of: 4x2, 4x4, track
  • 4x2 - Two-wheel drive
  • 4x4 - Four-wheel drive
  • track - Track/crawler system
​
name
string
Display name for the tractor. If not provided, defaults to brand + model.Example: "John Deere 6130M Premium"
​
weight_kg
number
Total weight in kilograms. Must be a positive number if provided.Example: 5200, 11200.5
​
traction_force_kn
number
Traction force in kilonewtons (kN). Must be a positive number if provided.Example: 45.5, 85.3
​
tire_type
string
Type of tires installed on the tractor.Example: "radial", "bias", "dual radial"
​
tire_width_mm
number
Tire width in millimeters. Must be a positive number if provided.Example: 540, 710
​
tire_diameter_mm
number
Tire diameter in millimeters. Must be a positive number if provided.Example: 1600, 1880
​
tire_pressure_psi
number
Recommended tire pressure in PSI. Must be a positive number if provided.Example: 15, 18, 12.5
​
status
string
default:"available"
Current status of the tractor. Must be one of: available, maintenance, inactiveDefaults to available if not specified.

​
Response Fields

​
success
boolean
Indicates if the request was successful
​
data
object
The newly created tractor object with all fields, including the generated tractor_id

​
Example Request

curl -X POST http://localhost:4000/api/tractors \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "name": "John Deere 6130M",
    "brand": "John Deere",
    "model": "6130M",
    "engine_power_hp": 130,
    "weight_kg": 5200,
    "traction_force_kn": 45.5,
    "traction_type": "4x4",
    "tire_type": "radial",
    "tire_width_mm": 540,
    "tire_diameter_mm": 1600,
    "tire_pressure_psi": 15,
    "status": "available"
  }'

​
Example Responses

{
  "success": true,
  "data": {
    "tractor_id": 15,
    "name": "John Deere 6130M",
    "brand": "John Deere",
    "model": "6130M",
    "engine_power_hp": 130,
    "weight_kg": 5200,
    "traction_force_kn": 45.5,
    "traction_type": "4x4",
    "tire_type": "radial",
    "tire_width_mm": 540,
    "tire_diameter_mm": 1600,
    "tire_pressure_psi": 15,
    "status": "available"
  }
}

​
Validation Rules

​
Required Fields (POST only)

1

Brand Validation

  • Must be provided
  • Must be a non-empty string
  • Cannot contain only whitespace
2

Model Validation

  • Must be provided
  • Must be a non-empty string
  • Cannot contain only whitespace
3

Engine Power Validation

  • Must be provided
  • Must be a number
  • Must be greater than 0
4

Traction Type Validation

  • Must be provided
  • Must be one of: 4x2, 4x4, track

​
Optional Field Validation

The following fields must be positive numbers if provided:
  • engine_power_hp
  • weight_kg
  • fuel_tank_l (if your database schema includes it)
Invalid values: 0, -10, "abc", null
If provided, must be one of:
  • available (default)
  • maintenance
  • inactive
Must be one of:
  • 4x2 - Two-wheel drive
  • 4x4 - Four-wheel drive (most common)
  • track - Track/crawler system

​
Error Responses

Returned when request body fails validation. The response includes an errors array with specific validation messages.Common validation errors:
  • "brand es requerido" - Brand field is missing
  • "model es requerido" - Model field is missing
  • "engine_power_hp es requerido" - Power field is missing
  • "engine_power_hp debe ser un número positivo" - Invalid power value
  • "traction_type es requerido" - Traction type is missing
  • "traction_type debe ser uno de: 4x2, 4x4, track" - Invalid traction type
  • "status debe ser uno de: available, maintenance, inactive" - Invalid status
Returned when no authentication token is provided in the request.Solution: Include a valid JWT token in the Authorization header.
Returned when the token is malformed, expired, or invalid.Solution: Login again to obtain a fresh token.
Returned when the authenticated user is not an administrator (role_id !== 1).Solution: This endpoint is restricted to administrators only. Regular users cannot create tractors.
Returned when an unexpected server error occurs (e.g., database connection issues, constraint violations).

​
Cache Invalidation

Creating a new tractor automatically invalidates all tractor-related caches. This ensures that GET requests to /api/tractors and search endpoints immediately reflect the new tractor.

List Tractors

View all tractors in the catalog

Update Tractor

Modify existing tractor details

Delete Tractor

Remove tractor from catalog

Authentication

Learn how to obtain admin credentials

Build docs developers (and LLMs) love

Get started for freeTalk to us