Register a field

POST

/v1/fields

curl --request POST \
  --url https://api.agrosat.uz/v1/fields \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --data '{ "name": "North parcel 3", "external_id": "f-1001", "geometry": { "type": "Polygon", "coordinates": [ [ [ 68.552, 40.3084 ], [ 68.56, 40.3084 ], [ 68.56, 40.3139 ], [ 68.552, 40.3139 ], [ 68.552, 40.3084 ] ] ] } }'

• Production

Registers a GeoJSON Polygon or MultiPolygon in WGS84 under your external_id and starts preparing its history. Repeating the request with the same external_id and geometry returns the existing field with 200. The field area is consumed from the contracted hectares and is not returned when the field is deleted or shrunk. Costs no units.

Authorizations

• apiKey

Request Body^required

Media typeapplication/json

object

name

required

string

<= 200 characters

Example

North parcel 3

external_id

required

Your identifier for the field, unique per organization

string

<= 128 characters

Example

f-1001

geometry

required

GeoJSON Polygon or MultiPolygon geometry in WGS84

object

type

required

string

Allowed values: Polygon MultiPolygon

coordinates

required

Polygon: array of rings; MultiPolygon: array of polygons

Array

Example

{
  "type": "Polygon",
  "coordinates": [
    [
      [
        68.552,
        40.3084
      ],
      [
        68.56,
        40.3084
      ],
      [
        68.56,
        40.3139
      ],
      [
        68.552,
        40.3139
      ],
      [
        68.552,
        40.3084
      ]
    ]
  ]
}

Responses

200

Same external_id and geometry: the existing field

Media typeapplication/json

object

success

required

boolean

data

required

object

id

required

string

external_id

required

string

name

required

string

area_ha

required

Area in hectares

number

status

required

Pending while history is prepared, then ready

string

Allowed values: pending ready

created_at

required

string format: date-time

Example

{
  "success": true,
  "data": {
    "id": "cmgz7k2qv0004l8p3a9d1x6rt",
    "external_id": "f-1001",
    "name": "North parcel 3",
    "area_ha": 41.53,
    "status": "pending",
    "created_at": "2026-04-28T09:14:03.512Z"
  }
}

201

Field registered; status is pending until history is prepared

Media typeapplication/json

object

success

required

boolean

data

required

object

id

required

string

external_id

required

string

name

required

string

area_ha

required

Area in hectares

number

status

required

Pending while history is prepared, then ready

string

Allowed values: pending ready

created_at

required

string format: date-time

Example

{
  "success": true,
  "data": {
    "id": "cmgz7k2qv0004l8p3a9d1x6rt",
    "external_id": "f-1001",
    "name": "North parcel 3",
    "area_ha": 41.53,
    "status": "pending",
    "created_at": "2026-04-28T09:14:03.512Z"
  }
}

400

The body or geometry is not acceptable

Media typeapplication/json

object

success

required

boolean

error

required

object

code

required

string

Allowed values: invalid_api_key rate_limited field_not_found invalid_geometry field_too_large duplicate_geometry external_id_conflict quota_exceeded invalid_index source_not_enabled invalid_date_range date_out_of_range no_imagery_for_date data_pending invalid_request not_found internal_error

message

required

English text; may change, branch on code

string

existing_field_id

Field already holding this external_id or geometry (409 only)

string

Examples

invalid_geometry

{
  "success": false,
  "error": {
    "code": "invalid_geometry",
    "message": "geometry must be GeoJSON in WGS84 (longitude, latitude)."
  }
}

field_too_large

{
  "success": false,
  "error": {
    "code": "field_too_large",
    "message": "Field area 6120.4 ha exceeds the 5000 ha per-field limit."
  }
}

invalid_request

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "external_id should not be empty"
  }
}

401

X-API-Key is missing, unknown, revoked or expired, or the API is not enabled.

Media typeapplication/json

object

success

required

boolean

error

required

object

code

required

string

Allowed values: invalid_api_key rate_limited field_not_found invalid_geometry field_too_large duplicate_geometry external_id_conflict quota_exceeded invalid_index source_not_enabled invalid_date_range date_out_of_range no_imagery_for_date data_pending invalid_request not_found internal_error

message

required

English text; may change, branch on code

string

existing_field_id

Field already holding this external_id or geometry (409 only)

string

Examples

Exampleinvalid_api_key

invalid_api_key

{
  "success": false,
  "error": {
    "code": "invalid_api_key",
    "message": "Missing or invalid API key."
  }
}

403

Contracted hectares are used up

Media typeapplication/json

object

success

required

boolean

error

required

object

code

required

string

Allowed values: invalid_api_key rate_limited field_not_found invalid_geometry field_too_large duplicate_geometry external_id_conflict quota_exceeded invalid_index source_not_enabled invalid_date_range date_out_of_range no_imagery_for_date data_pending invalid_request not_found internal_error

message

required

English text; may change, branch on code

string

existing_field_id

Field already holding this external_id or geometry (409 only)

string

Examples

Examplequota_exceeded

quota_exceeded

{
  "success": false,
  "error": {
    "code": "quota_exceeded",
    "message": "Contracted hectares exceeded (980.0/1000 ha consumed)."
  }
}

409

The field clashes with one you already registered

Media typeapplication/json

object

success

required

boolean

error

required

object

code

required

string

Allowed values: invalid_api_key rate_limited field_not_found invalid_geometry field_too_large duplicate_geometry external_id_conflict quota_exceeded invalid_index source_not_enabled invalid_date_range date_out_of_range no_imagery_for_date data_pending invalid_request not_found internal_error

message

required

English text; may change, branch on code

string

existing_field_id

Field already holding this external_id or geometry (409 only)

string

Examples

external_id_conflict

{
  "success": false,
  "error": {
    "code": "external_id_conflict",
    "message": "A field with this external_id already exists with a different geometry.",
    "existing_field_id": "cmgz7k2qv0004l8p3a9d1x6rt"
  }
}

duplicate_geometry

{
  "success": false,
  "error": {
    "code": "duplicate_geometry",
    "message": "Field overlaps 93% with existing field \"North parcel 3\". Duplicate fields are not allowed.",
    "existing_field_id": "cmgz7k2qv0004l8p3a9d1x6rt"
  }
}

429

Over the per-key request rate. Not billed.

Media typeapplication/json

object

success

required

boolean

error

required

object

code

required

string

Allowed values: invalid_api_key rate_limited field_not_found invalid_geometry field_too_large duplicate_geometry external_id_conflict quota_exceeded invalid_index source_not_enabled invalid_date_range date_out_of_range no_imagery_for_date data_pending invalid_request not_found internal_error

message

required

English text; may change, branch on code

string

existing_field_id

Field already holding this external_id or geometry (409 only)

string

Examples

Examplerate_limited

rate_limited

{
  "success": false,
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded."
  }
}

Headers

Retry-After

integer

Example

30

Seconds to wait before repeating the request