API Reference

tip

Refer to the Authentication Page for details on the Api-Key header required on every request.

FHI uses a single enrollment to define field boundaries, a monitoring period, and requested imagery layers. After submission, FHI handles backfill and ongoing daily processing automatically. Generated outputs are written to a deterministic storage path; use the SAS token API to obtain read access.

info

For the live, interactive contract view, see Swagger UI.
Raw OpenAPI spec: OpenAPI JSON

Submit Enrollment

POST /v1/enrollments

Accepts a multipart/form-data request with two file parts: enrollment metadata (JSON) and field boundaries (GeoJSON). Processing is asynchronous — the response acknowledges receipt without waiting for fields to be processed.

Request

Request Headers

{
    "Api-Key": "YOUR_API_KEY"
}

Form Parts

Part	Content Type	Description
request	application/json	Enrollment metadata: image_source, start_date, end_date, description, layers
geojson	application/geo+json	A FeatureCollection with one Feature per field. Each feature must include a Polygon (or MultiPolygon) geometry and a field_id property that uniquely identifies the field.

Sample request Part

{
  "image_source": "planet",
  "start_date": "2025-01-01",
  "end_date": "2025-12-31",
  "description": "meaningful customer description",
  "layers": [
    { "layer": "ndvi" },
    { "layer": "vegetation" },
    { "layer": "scouting" },
    { "layer": "true-color" }
  ]
}

Sample geojson Part

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": { "field_id": "field-us-1" },
      "geometry": {
        "type": "Polygon",
        "coordinates": [ [ [ -93.6, 41.6 ], [ -93.6, 41.61 ], [ -93.59, 41.61 ], [ -93.59, 41.6 ], [ -93.6, 41.6 ] ] ]
      }
    }
  ]
}

request Metadata Fields

Parameter	Description
image_source String	The satellite imagery source for the enrollment. Example: "planet"
start_date String	First date in the monitoring period. Format: YYYY-MM-DD
end_date String	Last date in the monitoring period. Format: YYYY-MM-DD
description String	Optional, customer-provided description of the enrollment.
layers Array	List of image types (layers) to generate for each field-date in the monitoring window.

Limits: maximum GeoJSON file size is 50 MB; maximum number of fields per enrollment is 250 (adjustable for specific use cases).

Response

Response Sample: 202 Accepted

{
  "enrollment_id": "id-1",
  "message": "Enrollment received OK.",
  "description": "meaningful customer description",
  "request_metadata": {
    "image_source": "planet",
    "start_date": "2025-01-01",
    "end_date": "2025-12-31",
    "layers": [
      { "layer": "ndvi" },
      { "layer": "vegetation" },
      { "layer": "scouting" },
      { "layer": "true-color" }
    ]
  },
  "status": "received",
  "total_fields": 1,
  "processed_fields": 0,
  "failed_fields": 0,
  "created_date_time": "2026-01-22T21:22:07.240796Z",
  "completed_date_time": null,
  "errors": null
}

Error Response Sample: 422 Validation Error

{
  "code": "string",
  "message": "string",
  "trace_id": "string",
  "details": null
}

Get Enrollment Status

GET /v1/enrollments/{enrollment_id}

Retrieves the current status of a previously submitted enrollment.

Request

Path Parameters

Parameter	Description
enrollment_id String	The enrollment_id returned when the enrollment was submitted.

Response

Response Sample: 200 OK

{
  "enrollment_id": "id-1",
  "message": "Enrollment received OK.",
  "description": "meaningful customer description",
  "request_metadata": {
    "image_source": "planet",
    "start_date": "2025-01-01",
    "end_date": "2025-12-31",
    "layers": [ { "layer": "ndvi" } ]
  },
  "status": "in_progress",
  "total_fields": 1,
  "processed_fields": 0,
  "failed_fields": 0,
  "created_date_time": "2026-01-22T21:22:07.240796Z",
  "completed_date_time": null,
  "errors": null
}

Possible status values: received, in_progress, completed, failed.

note

A completed status means the enrollment's fields and monitoring parameters were successfully ingested and scheduled. It does not guarantee imagery is available for every requested field-date — see FHI Overview for availability timelines and expected behavior.

List Enrollments

GET /v1/enrollments

Returns a paginated list of enrollments submitted by the caller.

Request

Query Parameters

Parameter	Description
status String	Optional filter. Options: received, in_progress, completed, failed
cursor String	Optional opaque cursor. Pass back the cursor value from the previous response to fetch the next page.
limit Integer	Optional page size. Default: 50

Response

Response Sample: 200 OK

{
  "items": [
    {
      "enrollment_id": "id-1",
      "message": "Enrollment received OK.",
      "description": "meaningful customer description",
      "request_metadata": { "image_source": "planet", "start_date": "2025-01-01", "end_date": "2025-12-31" },
      "status": "completed",
      "total_fields": 1,
      "processed_fields": 1,
      "failed_fields": 0,
      "created_date_time": "2026-01-22T21:22:07.240796Z",
      "completed_date_time": "2026-01-22T21:40:00.000000Z",
      "errors": null
    }
  ],
  "cursor": null
}

Get Storage Access (SAS Token)

GET /v1/auth/sas-token

Returns a time-limited SAS token granting read access to the storage container (or prefix) that holds generated imagery. The token is valid for the agreed duration (8 hours) and covers the customer's fhi/planet/ path hierarchy.

Response

Response Sample: 200 OK

{
  "account_name": "string",
  "file_system": "string",
  "sas_token": "string",
  "path": "{customer}/fhi/planet/"
}

Field	Description
account_name	The storage account name.
file_system	The storage container (file system) name.
sas_token	The SAS token granting read access.
path	The storage path/prefix the token applies to.

Use account_name, file_system, and sas_token with any storage-compatible SDK, CLI, or browser to list and download files under the deterministic path convention:

{customer}/fhi/planet/{field_id}/{date}/{image_type}.tiff

Example: bayer/fhi/planet/FIELD_001/2025-02-15/ndvi.tiff

See FHI Overview for the list of supported image_type values.