Skip to content
AgrovisioAgrovisio Data API

Postman collection

The collection is generated from /v1/openapi.json by agrovisio-backend/scripts/publicapi_docs_build.py and copied into this site on every build, so it is never older than the API it documents.

Download agrovisio-data-api.postman_collection.json

Import

Section titled “Import”

  1. In Postman choose Import, drop the downloaded file (or paste its URL from the link above).

  2. Open the collection’s Variables tab and set:

    Variable Value
    baseUrl https://api.agrovisio.ai/v1 (the default; sandbox and live keys share it)
    apiKey your sk_test_... sandbox key
    parcelId one of the sandbox parcel ids from GET /v1/parcels (for example the id of SBX-FIELD-01)
    webhookId only for GET / DELETE /v1/webhooks/{endpoint_id}: the id field of a POST /v1/webhooks response. Webhook ids are bare UUIDs, the one resource without a prc_ / job_ style prefix; the default is a placeholder UUID

  3. Send GET /v1/account first: it confirms the key and shows the plan, the scopes and the rate limits.

What the collection does for you

Section titled “What the collection does for you”
  • Authentication is set once at collection level as a bearer token from {{apiKey}}; every request inherits it.
  • Idempotency-Key is generated by a pre-request script on every POST - including the CAP calculations and POST /indices/batch, which require it like every other POST - so you can press Send repeatedly without idempotency_conflict; you can see a replay (Idempotent-Replay: true) by copying a key into the header manually and sending twice.
  • Requests are grouped by product, in the same order as the endpoint list, each with the example body from the OpenAPI document.

Sandbox scenarios worth running

Section titled “Sandbox scenarios worth running”
Request Set Expect
GET /parcels/{parcelId}/indices parcelId = SBX-NEW-1 422 baseline_not_ready with the X-Agrovisio-Not-Billable header; add baseline=false to get 200 with an empty series
GET /parcels/{parcelId}/indices parcelId = SBX-FIELD-01, add quality=good only good observations; observations counts what is returned (29 of 46 for April-September 2025)
GET /parcels/{parcelId}/thermal parcelId = SBX-SMALL-1 422 insufficient_resolution (area_ha: 1.68, Sentinel-3 needs 5 ha)
POST /damage/assess SBX-LODGING-1, 2025-07-04, storm 202, then GET /jobs/{job_id} completes with damage_pct: 85.0 at confidence 0.405 with direction_not_confirmed - certificate: null; GET /damage/{id}/certificate.pdf answers 422 insufficient_data (confidence_below_certificate_threshold)
POST /damage/assess SBX-FIELD-05, 2024-07-19, storm 202, then damage_pct: 0.0 at confidence 0.46 with the scenes proving nothing happened - no certificate
POST /damage/assess SBX-LODGING-3, 2024-07-03, storm damage_pct: 50.0 at confidence 0.5113: the certified case, by one hundredth; GET /damage/{id}/certificate.pdf answers 200 application/pdf
POST /damage/assess SBX-DROUGHT-1, 2023-07-20, drought the job completes with status: insufficient_data, reason: no_ndvi_observations, billable: false - the honest-failure path; the expensive pool allows 2 assessments per minute (a replay counts too), so pace these
GET /cap/rotation/check history=2022:winter_wheat,2023:winter_wheat,2024:winter_wheat,2025:winter_wheat compliant: false with one rotation_violation (consecutive_years: 4, limit_years: 3); with three seasons (2023-2025) the same call answers compliant: true - three in a row is still allowed

Numbers are from a fresh run on 2026-10-03 (damage-1.0, config_hash e3f43ecf61375aa8).

scripts/qa/int_postman_check.py in the backend repository fires every request of this collection against the sandbox before each release and fails on the first non-2xx, which is how the collection stays trustworthy.

Regenerating

Section titled “Regenerating”

When the API changes, regenerate the sources and rebuild the site. Only the backend directory is mounted into the container, so the script is pointed at a folder under it and the files are copied into docs/api afterwards:

Terminal window
docker compose -f agrovisio-backend/docker-compose.yml exec -T app \
  sh -c "cd /app && PUBLIC_API_DOCS_DIR=/app/_docs_build PYTHONPATH=/app \
         python -X utf8 scripts/publicapi_docs_build.py"
cp agrovisio-backend/_docs_build/* docs/api/ && rm -r agrovisio-backend/_docs_build
npm run build --prefix agrovisio-docs