API contracts / App Service v2 / Farming models

A farmer's ATM plots and DKG answers

OperationlistFarmerFarmingModels
Call
GET /gateway/urvi-app-service/api/v2/farmers/{farmerId}/farming-models
Group
Farming models
Features
ATM model (Anytime Money plot), ATM harvest, 365 DKG kitchen garden
Replaces today

Use case. Called online by the ATM and 365 DKG screens on refresh. Returns the latest version per ATM tileId (with crop lines and harvest status) and DKG monthly answers, with photo and geofence URLs.

Rules.

  • ATMs whose every line is COMPLETED are returned with harvestStatus COMPLETED; the app hides them.

Error codes. NOT_FOUND

Parameters

NameInTypeRequiredMeaningExample
X-App-VersionheaderstringYesApp version `major.minor.patch+build`. Too old -> 426 `VERSION_TOO_OLD`. · pattern ^\d+\.\d+\.\d+(\+\d+)?$2.0.0+200
X-Device-Idheaderstring (uuid)YesApp-scoped device UUID (not ANDROID_ID).6b1f2c3d-0000-4000-8000-00000000d001
X-Request-Idheaderstring (uuid)NoClient-generated request id for tracing; echoed in responses and problems.0e0c5a1b-0000-4000-8000-0000000000a1
Accept-LanguageheaderstringNoLanguage for messages and labels. · one of en, te, ta; default "en"te
X-TenantheaderstringNoTenant code; must match the token. Urvi: `ap.gov`. · one of ap.govap.gov
farmerIdpathstringYesFarmer server id or client UUID (`aliasId`). With a UUID unknown to the server, the farmer is created from the flat master record (get-or-create). · min length 1; max length 643f6c1a2e-0000-4000-8000-00000000f001
modelTypequerystringNoFilter by type. · one of ATM, DKG_365ATM

Request

No body.

Responses

200 Farming models.

Schema FarmingModel.

Example 200 body
[
  {
    "id": 850001,
    "clientId": "6c9f4d5b-0000-4000-8000-000000012289",
    "version": 2,
    "createdAt": "2025-08-01T09:00:00+05:30",
    "updatedAt": "2025-10-14T09:30:00+05:30",
    "active": true,
    "modelType": "ATM",
    "farmerId": 700001,
    "farmerClientId": "3f6c1a2e-0000-4000-8000-000000061441",
    "landId": 810001,
    "landClientId": "4a7d2b3f-0000-4000-8000-000000004097",
    "landChecksum": "c1a5e0d7",
    "tileId": "ATM-850001",
    "landAcres": 0.25,
    "raisedBeds": true,
    "vegetableCrops": [
      {
        "clientId": "6c9f4d5b-0000-4000-8000-000000012545",
        "productCode": "TOMATO",
        "lineType": "VEGETABLE",
        "harvestStatus": "PENDING"
      }
    ],
    "relayCropping": false,
    "maizeCultivation": true,
    "pulseCrops": [
      {
        "clientId": "6c9f4d5b-0000-4000-8000-000000012546",
        "productCode": "GREEN_GRAM",
        "lineType": "PULSE",
        "harvestStatus": "PENDING"
      }
    ],
    "practiceCodes": [
      "AP-GOV-KAP-BEEJAMRUTHAM"
    ],
    "incomeGeneration": true,
    "incomeGenerationDetails": 3500,
    "photo": {
      "fileId": "7a6b5c4d-0000-4000-8000-000000000225",
      "kind": "PHOTO_ATM",
      "url": "https://files.example.invalid/urvi/signed/atm-850001.jpg"
    },
    "harvestStatus": "PENDING"
  },
  {
    "id": 850002,
    "clientId": "6c9f4d5b-0000-4000-8000-000000012290",
    "version": 1,
    "modelType": "DKG_365",
    "farmerId": 700001,
    "farmerClientId": "3f6c1a2e-0000-4000-8000-000000061441",
    "month": "2025-10",
    "continuing": true,
    "active": true
  }
]

400 Malformed request or schema violation.

Schema Problem.

Example 400 body
{
  "type": "https://urvi.example.invalid/problems/validation-failed",
  "title": "Validation failed",
  "status": 400,
  "detail": "One or more fields are invalid.",
  "code": "VALIDATION_FAILED",
  "requestId": "0e0c5a1b-0000-4000-8000-0000000000a1",
  "errors": [
    {
      "field": "/mobile",
      "code": "INVALID_MOBILE",
      "message": "Mobile must be 10 digits starting 6-9."
    }
  ]
}

401 Missing, invalid or expired access token. Refresh once, then ask the user to log in; pending outbox ops stay intact.

Schema Problem.

Example 401 body
{
  "type": "https://urvi.example.invalid/problems/token-expired",
  "title": "Session expired",
  "status": 401,
  "detail": "The access token has expired.",
  "code": "TOKEN_EXPIRED",
  "requestId": "0e0c5a1b-0000-4000-8000-0000000000a1"
}

403 Authenticated but not allowed (role, tenant, device binding or feature switch).

Schema Problem.

Example 403 body
{
  "type": "https://urvi.example.invalid/problems/role-not-allowed",
  "title": "Not allowed",
  "status": 403,
  "detail": "Your role cannot perform this action.",
  "code": "ROLE_NOT_ALLOWED",
  "requestId": "0e0c5a1b-0000-4000-8000-0000000000a1"
}

404 Resource not found or outside the user's work nodes.

Schema Problem.

Example 404 body
{
  "type": "https://urvi.example.invalid/problems/not-found",
  "title": "Not found",
  "status": 404,
  "detail": "No such resource in your work area.",
  "code": "NOT_FOUND",
  "requestId": "0e0c5a1b-0000-4000-8000-0000000000a1"
}

426 App version below the minimum; block the UI with an update prompt. Pending outbox ops are kept.

Schema Problem.

Example 426 body
{
  "type": "https://urvi.example.invalid/problems/version-too-old",
  "title": "Update required",
  "status": 426,
  "detail": "Please update Urvi to continue.",
  "code": "VERSION_TOO_OLD",
  "requestId": "0e0c5a1b-0000-4000-8000-0000000000a1",
  "minAppVersion": "2.0.0"
}

429 Rate limited per device / user. Respect `Retry-After`.

Schema Problem.

Example 429 body
{
  "type": "https://urvi.example.invalid/problems/rate-limited",
  "title": "Too many requests",
  "status": 429,
  "detail": "Slow down and retry later.",
  "code": "RATE_LIMITED",
  "requestId": "0e0c5a1b-0000-4000-8000-0000000000a1",
  "retryAfterSeconds": 30
}

500 Unexpected server error; retry with backoff (writes are idempotent).

Schema Problem.

Example 500 body
{
  "type": "https://urvi.example.invalid/problems/internal-error",
  "title": "Server error",
  "status": 500,
  "detail": "Something went wrong. Please try again.",
  "code": "INTERNAL_ERROR",
  "requestId": "0e0c5a1b-0000-4000-8000-0000000000a1"
}