Gigbest Copilot

Developer & Terminal Integration

Gigbest Copilot REST API Documentation

Complete guide to integrating with the Gigbest Copilot cloud API. Generate API keys, synchronize AgOpenGPS and AgOpenWeb field boundaries, manage guidance AB lines, and backup tractor auto-steer configuration profiles.

Generate API Key Field Boundaries Tractor Settings In-Cab Setup

Overview & Architecture

The Gigbest Copilot API connects farm machinery in-cab terminals (running AgOpenGPS or custom Gigbest Copilot tablet consoles) with the central farmer portal and cloud infrastructure. It enables automatic two-way synchronization of:

  • Field Boundaries & Obstacles: Outer polygon perimeters and internal exclusion zones (trees, wells, solar pump stations, electric poles).
  • Guidance AB Lines & Contours: Centimetre-accurate sowing, ridging, spraying, and harvesting tracks.
  • Tractor Settings Profiles: Vehicle geometry (wheelbase, track width), GNSS antenna offsets, wheel angle sensor (WAS) calibration, and auto-steering PID controller tuning parameters.
Environment Base URL Notes
Production API https://api.gigbest.com Dedicated high-speed endpoint for in-cab tablet terminals & mobile apps.
Web Mirror Gateway https://gigbest.com/api Standard web reverse proxy mirror endpoint.
Local Development http://localhost/api Local development and staging test environment.

Standard Data Format: All API requests and responses use standard JSON (application/json; charset=utf-8). Timestamps are returned in ISO 8601 UTC format (YYYY-MM-DDTHH:MM:SSZ).

Step 1: Generating Your API Key

All field boundary and tractor profile operations require a Gigbest Field Share API Key. Keys are generated directly within the Gigbest Farmer Portal and are cryptographically scoped to your farmer account.

1

Log In to Portal

Sign in at gigbest.com/portal/login.php using your registered farmer mobile number or email and password.

2

Go to My Profile

In the farmer dashboard menu, select My Profile (or visit /farmer/my-profile.php) and scroll to Field Share API Key.

3

Generate or Set Key

Click Generate API Key for a cryptographic 48-byte secure token, or optionally input a custom key (32–120 characters).

4

Copy & Store Key

Copy the full key immediately. For security, only the key prefix is retained in the portal display after generation.

Key Security Notice: Generated keys follow the format gbfs_<48-hex-characters> (for example: gbfs_e4d92a108fbc51307b992147ae620c3881df6078e9b41a35). The server stores only a SHA-256 hash. If your key is lost or compromised, return to My Profile and click Regenerate API Key to immediately revoke the old key and create a new one.

Step 2: Authentication & HTTP Headers

Authenticate every request by passing your API key in the standard Authorization header using the ApiKey scheme:

HTTP Request Header 
Authorization: ApiKey gbfs_e4d92a108fbc51307b992147ae620c3881df6078e9b41a35

Required Headers

Header Value Requirement
Authorization ApiKey <your-api-key> Required on all routes
Content-Type application/json Required on POST and PUT
Accept application/json Recommended

Verify Your API Key

You can quickly verify that your API key is active and correctly authorized with a simple cURL test:

Bash / cURL 
curl -s -X GET "https://api.gigbest.com/fields" \
  -H "Authorization: ApiKey gbfs_e4d92a108fbc51307b992147ae620c3881df6078e9b41a35" \
  -H "Accept: application/json"

Field Boundaries & Guidance Lines API

Gigbest Copilot natively implements the AgOpenGPS & AgOpenWeb boundary format. Coordinates are expressed in standard WGS84 decimal degrees (Latitude, Longitude).

Boundary Data Model Structure

  • origin: The central WGS84 reference anchor for the field.
  • boundary.outer: Array of GPS coordinates forming the outer perimeter ring (minimum 3 coordinates, up to 50,000 coordinates).
  • boundary.holes: Optional array of inner polygon rings representing obstacle exclusion zones (wells, farm buildings, trees, electric towers).
  • abLines: Parallel guidance lines and curve tracks recorded for auto-steering passes.
PUT /api/fields/{field_uuid}
Max Payload: 5 MB

Creates or updates an AgOpenWeb-compatible field boundary in your cloud account. The {field_uuid} path parameter must be a standard lowercase UUID v4.

URL Path Parameters

Parameter Type Description
field_uuid string (UUID) Unique field identifier (e.g. 9f8e4c32-b7d6-44c1-8419-f5383a1e9411).

Request Body JSON Schema

JSON Request Payload 
{
  "name": "Thordi Farm - North Cotton Plot",
  "isPublic": false,
  "origin": {
    "latitude": 22.3038945,
    "longitude": 70.8021598
  },
  "boundary": {
    "outer": [
      { "latitude": 22.3045100, "longitude": 70.8015200 },
      { "latitude": 22.3045250, "longitude": 70.8032400 },
      { "latitude": 22.3031000, "longitude": 70.8032100 },
      { "latitude": 22.3030800, "longitude": 70.8015000 },
      { "latitude": 22.3045100, "longitude": 70.8015200 }
    ],
    "holes": [
      [
        { "latitude": 22.3038000, "longitude": 70.8022000 },
        { "latitude": 22.3039000, "longitude": 70.8023500 },
        { "latitude": 22.3037500, "longitude": 70.8024000 },
        { "latitude": 22.3038000, "longitude": 70.8022000 }
      ]
    ]
  },
  "abLines": [
    {
      "name": "North-South Main Sowing Pass 180°",
      "type": "ABLine",
      "coords": [
        { "latitude": 22.3045100, "longitude": 70.8020000 },
        { "latitude": 22.3031000, "longitude": 70.8020000 }
      ]
    }
  ],
  "convergence": 0.0,
  "sourceId": "tablet-unit-01"
}

cURL Upload Example

cURL Command 
curl -s -X PUT "https://api.gigbest.com/fields/9f8e4c32-b7d6-44c1-8419-f5383a1e9411" \
  -H "Authorization: ApiKey gbfs_e4d92a108fbc51307b992147ae620c3881df6078e9b41a35" \
  -H "Content-Type: application/json" \
  -d @field_payload.json

Success Response (HTTP 200 OK)

JSON Response 
{
  "id": "9f8e4c32-b7d6-44c1-8419-f5383a1e9411",
  "message": "Field backup saved"
}
GET /api/fields/{field_uuid}
AgOpenWeb Format

Downloads the complete boundary rings and guidance AB lines for a specific field so the tractor in-cab terminal can load it for guidance.

cURL Command

cURL Command 
curl -s -X GET "https://api.gigbest.com/fields/9f8e4c32-b7d6-44c1-8419-f5383a1e9411" \
  -H "Authorization: ApiKey gbfs_e4d92a108fbc51307b992147ae620c3881df6078e9b41a35" \
  -H "Accept: application/json"

Response Payload (HTTP 200 OK)

JSON Response 
{
  "id": "9f8e4c32-b7d6-44c1-8419-f5383a1e9411",
  "name": "Thordi Farm - North Cotton Plot",
  "isPublic": false,
  "createdAt": "2026-10-08T09:15:30Z",
  "latitude": 22.3038945,
  "longitude": 70.8021598,
  "boundaries": [
    [
      { "latitude": 22.3045100, "longitude": 70.8015200 },
      { "latitude": 22.3045250, "longitude": 70.8032400 },
      { "latitude": 22.3031000, "longitude": 70.8032100 },
      { "latitude": 22.3030800, "longitude": 70.8015000 }
    ],
    [
      { "latitude": 22.3038000, "longitude": 70.8022000 },
      { "latitude": 22.3039000, "longitude": 70.8023500 },
      { "latitude": 22.3037500, "longitude": 70.8024000 }
    ]
  ],
  "abLines": [
    {
      "name": "North-South Main Sowing Pass 180°",
      "type": "ABLine",
      "coords": [
        { "latitude": 22.3045100, "longitude": 70.8020000 },
        { "latitude": 22.3031000, "longitude": 70.8020000 }
      ]
    }
  ]
}
GET /api/fields
AgShare List Format

Lists all fields backed up for the authenticated farmer. Returns lightweight metadata consumed by the AgOpenGPS field chooser screen.

cURL Command

cURL Command 
curl -s -X GET "https://api.gigbest.com/fields" \
  -H "Authorization: ApiKey gbfs_e4d92a108fbc51307b992147ae620c3881df6078e9b41a35"

Response Payload (HTTP 200 OK)

JSON Response Array 
[
  {
    "id": "9f8e4c32-b7d6-44c1-8419-f5383a1e9411",
    "name": "Thordi Farm - North Cotton Plot",
    "latitude": 22.3038945,
    "longitude": 70.8021598,
    "createdAt": "2026-10-08T09:15:30Z",
    "isPublic": false
  },
  {
    "id": "5a1c8f44-1234-4b5c-9d0e-778899aabbcc",
    "name": "Rajkot Bypass - Groundnut Bed Plot",
    "latitude": 22.2854120,
    "longitude": 70.7812500,
    "createdAt": "2026-09-24T14:20:10Z",
    "isPublic": false
  }
]

Tractor Settings & Vehicle Profiles API

Every tractor has unique mechanical and electronic geometry. Backing up vehicle profiles to the Gigbest Cloud enables:

  • Instant Machine Swapping: Move one Gigbest Copilot tablet between different tractors (e.g. Mahindra 575 DI, John Deere 5310, Swaraj 855) and restore the exact steering configuration in seconds.
  • Disaster Recovery: If an in-cab tablet is damaged or reset in the field, technicians or farmers can restore steering calibration with one click.
  • Remote Calibration: Gigbest technicians can inspect steering gains and optimize Stanley/Pure Pursuit parameters remotely.
POST /api/settings
Max Payload: 2 MB

Creates or replaces a named vehicle profile backup. Profile names are trimmed, limited to 100 characters, and matched case-insensitively.

Vehicle Configuration Parameters

Parameter Group Key Settings Included
vehicle Wheelbase (cm), track width, hitch offset, tool width, overlap, implement type.
gps Antenna height, antenna fore/aft offset, lateral offset, NMEA baud rate (115200), RTK mode.
guidance Lookahead distance, Stanley controller gain, Pure Pursuit gain, integral/proportional gains.
youTurn Automated headland turn radius, turn style, boundary margin, row skip configuration.
autoSteer Motor PWM min/max, steering wheel encoder counts per degree, WAS zero offset, deadband.

Request Body JSON Schema

JSON Request Payload 
{
  "kind": "gigbestcopilot.vehicle-profile",
  "formatVersion": 1,
  "profileName": "Mahindra 575 DI - Sowing Setup",
  "exportedAtUtc": "2026-10-08T10:30:00Z",
  "vehicleProfile": {
    "formatVersion": 2,
    "name": "Mahindra 575 DI - Sowing Setup",
    "vehicle": {
      "wheelbaseCm": 197,
      "trackWidthCm": 142,
      "hitchLengthCm": 65,
      "toolWidthCm": 180,
      "toolOffsetCm": 0
    },
    "gps": {
      "antennaHeightCm": 235,
      "antennaForeAftOffsetCm": 25,
      "antennaLateralOffsetCm": 0,
      "baudRate": 115200,
      "rtkFixRequired": true
    },
    "guidance": {
      "controllerType": "Stanley",
      "stanleyGain": 1.25,
      "stanleyHeadingGain": 1.05,
      "lookaheadSeconds": 2.2,
      "proportionalGain": 45,
      "integralGain": 12
    },
    "youTurn": {
      "turnRadiusMeters": 4.5,
      "headlandTurnStyle": "Keyhole",
      "boundaryMarginMeters": 2.0
    },
    "autoSteer": {
      "minPwm": 28,
      "maxPwm": 240,
      "countsPerDegree": 112,
      "wasZeroOffset": 512,
      "deadband": 2
    },
    "general": {
      "units": "metric",
      "audioAlertsEnabled": true
    }
  }
}

cURL Upload Command

cURL Command 
curl -s -X POST "https://api.gigbest.com/settings" \
  -H "Authorization: ApiKey gbfs_e4d92a108fbc51307b992147ae620c3881df6078e9b41a35" \
  -H "Content-Type: application/json" \
  -d @mahindra_profile.json

Response Payload (HTTP 200 OK)

JSON Response 
{
  "success": true,
  "profileName": "Mahindra 575 DI - Sowing Setup",
  "message": "Vehicle profile backup uploaded successfully.",
  "updatedAt": "2026-10-08T10:30:00Z"
}
GET /api/settings?profileName={name}
Profile Download

Downloads the complete stored backup envelope for the specified tractor profile name. profileName is a required query parameter.

cURL Command

cURL Command 
curl -s -X GET "https://api.gigbest.com/settings?profileName=Mahindra%20575%20DI%20-%20Sowing%20Setup" \
  -H "Authorization: ApiKey gbfs_e4d92a108fbc51307b992147ae620c3881df6078e9b41a35" \
  -H "Accept: application/json"

Success Response (HTTP 200 OK)

Returns the complete vehicle profile envelope stored during upload.

GET /api/settings/profiles
Profiles Listing

Lists available profile names and their creation/update timestamps for the authenticated farmer account.

cURL Command

cURL Command 
curl -s -X GET "https://api.gigbest.com/settings/profiles" \
  -H "Authorization: ApiKey gbfs_e4d92a108fbc51307b992147ae620c3881df6078e9b41a35"

Response Payload (HTTP 200 OK)

JSON Response 
{
  "profiles": [
    {
      "profileName": "Mahindra 575 DI - Sowing Setup",
      "createdAt": "2026-10-08T10:30:00Z",
      "updatedAt": "2026-10-08T10:30:00Z"
    },
    {
      "profileName": "John Deere 5310 - Spraying Rig",
      "createdAt": "2026-09-12T08:15:00Z",
      "updatedAt": "2026-10-02T16:45:00Z"
    }
  ]
}
DELETE /api/settings?profileName={name}
Profile Removal

Permanently deletes the specified profile from your cloud account.

cURL Command

cURL Command 
curl -s -X DELETE "https://api.gigbest.com/settings?profileName=Mahindra%20575%20DI%20-%20Sowing%20Setup" \
  -H "Authorization: ApiKey gbfs_e4d92a108fbc51307b992147ae620c3881df6078e9b41a35"

Response Payload (HTTP 200 OK)

JSON Response 
{
  "success": true,
  "message": "Vehicle profile backup deleted successfully."
}

In-Cab Terminal & Tablet Integration

Follow these steps to connect your tractor in-cab display (running AgOpenGPS or the Gigbest Tablet Console) to your cloud account:

1

Open Terminal Settings

Turn on the tractor tablet. Launch AgOpenGPS and tap the Settings (Gear) > Cloud & AgShare Sync menu.

2

Enter Server URL

Set Server URL to https://api.gigbest.com (or your designated local network mirror).

3

Paste Your API Key

Enter your Field Share API key generated in Step 1 into the API Key field.

4

Test Connection

Tap Test Connection. A green badge indicates active authentication. Enable Auto-sync on boot.

Offline-First Resilience in Indian Farming Conditions

Mobile cellular internet connectivity can be intermittent in rural farm fields across Saurashtra, Gujarat, and wider India. Gigbest Copilot was architected from the ground up for offline-first operation:

  • Local Tablet Caching: All downloaded field boundaries, exclusion zones, and steering calibration profiles are stored in local flash memory on the tablet.
  • Zero Downtime in Remote Fields: Auto-steering operates with full 2.5 cm RTK centimeter accuracy completely offline using local radio or base station signals.
  • Background Auto-Sync: Once the tractor returns to cellular coverage or farm WiFi, newly recorded field boundaries and guidance lines synchronize to the Gigbest portal automatically.

Code Samples & SDK Integration

Complete runnable code snippets for automating field management and vehicle profile synchronization.

Python 3 (using requests)

Python Client Example 
import requests
import json
import uuid

API_BASE = "https://api.gigbest.com"
API_KEY = "gbfs_e4d92a108fbc51307b992147ae620c3881df6078e9b41a35"

headers = {
    "Authorization": f"ApiKey {API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json"
}

# 1. List all field boundaries
def list_fields():
    resp = requests.get(f"{API_BASE}/fields", headers=headers)
    resp.raise_for_status()
    fields = resp.json()
    print(f"Found {len(fields)} fields:")
    for f in fields:
        print(f" - {f['name']} ({f['latitude']}, {f['longitude']})")
    return fields

# 2. Upload a new field boundary
def upload_field(field_name, lat, lon):
    field_id = str(uuid.uuid4())
    payload = {
        "name": field_name,
        "isPublic": False,
        "origin": {"latitude": lat, "longitude": lon},
        "boundary": {
            "outer": [
                {"latitude": lat + 0.001, "longitude": lon - 0.001},
                {"latitude": lat + 0.001, "longitude": lon + 0.001},
                {"latitude": lat - 0.001, "longitude": lon + 0.001},
                {"latitude": lat - 0.001, "longitude": lon - 0.001}
            ],
            "holes": []
        },
        "abLines": [
            {
                "name": "Sowing Line 1",
                "type": "ABLine",
                "coords": [
                    {"latitude": lat + 0.001, "longitude": lon},
                    {"latitude": lat - 0.001, "longitude": lon}
                ]
            }
        ]
    }
    resp = requests.put(f"{API_BASE}/fields/{field_id}", headers=headers, json=payload)
    resp.raise_for_status()
    print("Field uploaded successfully:", resp.json())
    return field_id

# 3. Download a tractor steering profile
def get_tractor_profile(profile_name):
    params = {"profileName": profile_name}
    resp = requests.get(f"{API_BASE}/settings", headers=headers, params=params)
    if resp.status_code == 200:
        print(f"Profile '{profile_name}' downloaded successfully.")
        return resp.json()
    elif resp.status_code == 404:
        print(f"Profile '{profile_name}' not found.")
    return None

if __name__ == "__main__":
    list_fields()

JavaScript / Node.js (using fetch)

Node.js / ES6 Example 
const API_BASE = 'https://api.gigbest.com';
const API_KEY = 'gbfs_e4d92a108fbc51307b992147ae620c3881df6078e9b41a35';

async function listTractorProfiles() {
  const response = await fetch(`${API_BASE}/settings/profiles`, {
    headers: {
      'Authorization': `ApiKey ${API_KEY}`,
      'Accept': 'application/json'
    }
  });

  if (!response.ok) {
    throw new Error(`API error: ${response.status} ${response.statusText}`);
  }

  const data = await response.json();
  console.log('Saved tractor profiles:', data.profiles);
}

listTractorProfiles().catch(console.error);

HTTP Status Codes & Troubleshooting

The Gigbest Copilot API returns conventional HTTP response codes to indicate the success or failure of requests:

Status Code Meaning Description & Suggested Action
200 OK Success The request succeeded. Requested data or confirmation is returned.
400 Bad Request Invalid Request Request payload is not valid JSON, missing required fields (e.g. profileName), or contains schema errors.
401 Unauthorized Auth Failure Missing or invalid ApiKey in the Authorization header. Check your key in the Farmer Portal.
403 Forbidden Not Permitted Account is not active or not in approved farmer status. Contact Gigbest customer support.
404 Not Found Resource Missing The specified field_uuid or profileName does not exist in your account.
405 Method Not Allowed Wrong Verb The HTTP method is not supported on this endpoint (e.g. calling POST on /fields instead of PUT on /fields/{id}).
413 Payload Too Large Size Exceeded Request exceeds maximum payload size: 5 MB for field boundaries, 2 MB for vehicle profiles.
422 Unprocessable Geometry Error Field boundary coordinates are invalid (fewer than 3 points, coordinates outside WGS84 range, etc.).
500 Internal Error Server Error An unexpected server error occurred. Try again or notify Gigbest technical support.

Need Developer or On-Site Integration Help?

Our engineering and field support team is based in Rajkot, Gujarat, providing on-site assistance for farm telemetry and custom equipment integration.

Log In to Farmer Portal Contact Engineering Support WhatsApp Support