Skip to main content
Use the satellite service to register geometries for monitoring, retrieve processed image captures, and manage Planet subscriptions or reprocessing. This page is the endpoint reference for Sentinel and Planet imagery once you already understand the product-level behavior. For conceptual background, see Satellite Imagery Overview.

​
Base URL

https://api.withleaf.io/services/satellite/api

​
Endpoints

EndpointMethodPath
Get all satellite fieldsGET/fields
Get a satellite fieldGET/fields/{id}
Get images of satellite fieldGET/fields/{id}/processes
Get an image of satellite fieldGET/fields/{id}/processes/{processId}
Create a satellite fieldPOST/fields
Delete a satellite fieldDELETE/fields/{id}
Get subscription for PlanetGET/fields/{id}/subscription
Reprocess satellite imagesPOST/fields/{id}/process/{processId}/reprocess
Planet imagery is billed per area processed. Every satellite field with Planet in its providers array consumes quota when new imagery is processed. Use a small test geometry when validating your integration.

​
Get all satellite fields

GET /fields Returns a paginated list of satellite fields for the authenticated API owner.

​
Parameters

ParameterTypeDescription
pageintegerPage number (default 0).
sizeintegerPage size (default 20, max 100).
sortstringSorting order. Valid fields: createdAt, providers, externalId. Append ,asc or ,desc (e.g. createdAt,desc).

​
Request

curl -X GET \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  'https://api.withleaf.io/services/satellite/api/fields?page=0&size=10&sort=createdAt,desc'

​
Response

[
  {
    "id": "b2a3c4d5-e6f7-4890-abcd-ef1234567890",
    "externalId": "north-quarter",
    "geometry": {
      "type": "MultiPolygon",
      "coordinates": [[[
        [-93.48821, 41.77137],
        [-93.48817, 41.77143],
        [-93.48821, 41.76068],
        [-93.48821, 41.77137]
      ]]]
    },
    "providers": ["Sentinel"],
    "createdAt": "2023-07-21T13:01:11Z"
  }
]

​
Get a satellite field

GET /fields/{id} Returns a single satellite field by ID.

​
Parameters

ParameterTypeDescription
idpath (UUID)The satellite field ID.

​
Request

curl -X GET \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  'https://api.withleaf.io/services/satellite/api/fields/{id}'

​
Response

Returns a single satellite field object (same shape as the objects in the Get all satellite fields response).

​
Get images of satellite field

GET /fields/{id}/processes Returns a paginated list of processed satellite images for the specified field. Each process represents a single capture date and contains one or more image types (NDVI, RGB, etc.).

​
Parameters

ParameterTypeDescription
idpath (UUID)The satellite field ID.
startDatestringISO 8601 date. Returns images captured on or after this date.
endDatestringISO 8601 date. Returns images captured on or before this date.
startProcessedTimestampstringISO 8601 timestamp. Returns images processed on or after this time.
endProcessedTimestampstringISO 8601 timestamp. Returns images processed on or before this time.
maxCloudsnumberMaximum cloud percentage to include, from 0.0 to 100.0.
minCoveragenumberMinimum field coverage percentage to include, from 0.0 to 100.0.
providerstringFilter by provider: sentinel or planet.
pageintegerPage number (default 0).
sizeintegerPage size (default 20, max 100).
sortstringSorting order with optional ,asc or ,desc suffix (e.g. date,desc).

​
Request

curl -X GET \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  'https://api.withleaf.io/services/satellite/api/fields/{id}/processes?startDate=2020-09-07&endDate=2020-09-10&provider=sentinel&page=0&size=10&sort=date,desc'

​
Response

[
  {
    "id": "c3d4e5f6-a7b8-4901-cdef-ab1234567890",
    "date": "2020-09-07T19:03:57.882Z",
    "clouds": 0,
    "provider": "sentinel",
    "status": "SUCCESS",
    "coverage": 100,
    "images": [
      {
        "url": "https://satellite-imagery.withleaf.io/ndvi/c3d4e5f6.png",
        "downloadUrl": "https://satellite-imagery.withleaf.io/ndvi/c3d4e5f6.tif",
        "type": "NDVI"
      },
      {
        "url": "https://satellite-imagery.withleaf.io/rgb/c3d4e5f6.png",
        "downloadUrl": "https://satellite-imagery.withleaf.io/rgb/c3d4e5f6.tif",
        "type": "RGB"
      }
    ],
    "processedTimestamp": "2020-09-07T19:03:58.881731Z"
  }
]

​
Get an image of satellite field

GET /fields/{id}/processes/{processId} Returns a single satellite image process by ID.

​
Parameters

ParameterTypeDescription
idpath (UUID)The satellite field ID.
processIdpath (UUID)The process ID.

​
Request

curl -X GET \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  'https://api.withleaf.io/services/satellite/api/fields/{id}/processes/{processId}'

​
Response

Returns a single process object (same shape as the objects in the Get images of satellite field response).

​
Create a satellite field

POST /fields Creates a satellite field and begins imagery processing. Once created, Leaf fetches available satellite imagery for the geometry from the specified providers.

​
Parameters

ParameterTypeDescription
externalIdstring (required)Your identifier for the field.
geometryGeoJSON MultiPolygon (required)The field boundary.
providersarray of strings (optional)Satellite providers to enable. Accepted values: sentinel, planet. Defaults to ["sentinel"] if omitted.
Start with sentinel for development and testing. Add planet when you need higher-resolution imagery in production.

​
Request body

{
  "externalId": "north-quarter",
  "geometry": {
    "type": "MultiPolygon",
    "coordinates": [[[
      [-93.48821, 41.77137],
      [-93.48817, 41.77143],
      [-93.48821, 41.76068],
      [-93.48821, 41.77137]
    ]]]
  },
  "providers": ["sentinel"]
}

​
Request

curl -X POST \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"externalId":"north-quarter","geometry":{"type":"MultiPolygon","coordinates":[[[[-93.48821,41.77137],[-93.48817,41.77143],[-93.48821,41.76068],[-93.48821,41.77137]]]]},"providers":["sentinel"]}' \
  'https://api.withleaf.io/services/satellite/api/fields'

​
Response

{
  "id": "b2a3c4d5-e6f7-4890-abcd-ef1234567890",
  "externalId": "north-quarter",
  "geometry": {
    "type": "MultiPolygon",
    "coordinates": [[[
      [-93.48821, 41.77137],
      [-93.48817, 41.77143],
      [-93.48821, 41.76068],
      [-93.48821, 41.77137]
    ]]]
  },
  "providers": ["sentinel"],
  "createdAt": "2023-07-21T13:01:11Z"
}

​
Delete a satellite field

DELETE /fields/{id} Deletes a satellite field and stops all future imagery processing for it.

​
Parameters

ParameterTypeDescription
idpath (UUID)The satellite field ID.

​
Request

curl -X DELETE \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  'https://api.withleaf.io/services/satellite/api/fields/{id}'

​
Get subscription for Planet

GET /fields/{id}/subscription Returns the Planet subscription status for a satellite field. This endpoint only applies to fields that have Planet in their providers array.

​
Parameters

ParameterTypeDescription
idpath (UUID)The satellite field ID.

​
Request

curl -X GET \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  'https://api.withleaf.io/services/satellite/api/fields/{id}/subscription'

​
Response

{
  "fieldId": "b2a3c4d5-e6f7-4890-abcd-ef1234567890",
  "provider": "Planet",
  "status": "ACTIVE"
}

​
Reprocess satellite images

POST /fields/{id}/process/{processId}/reprocess Triggers reprocessing for a specific satellite image. Use this if a process failed or if you need updated imagery outputs.

​
Parameters

ParameterTypeDescription
idpath (UUID)The satellite field ID.
processIdpath (UUID)The process ID to reprocess.

​
Request

curl -X POST \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  'https://api.withleaf.io/services/satellite/api/fields/{id}/process/{processId}/reprocess'
Last modified on March 24, 2026