Skip to content
AgrovisioAgrovisio Data API

Changelog

Subscribe to the RSS feed to be notified of every entry. Adding a field is never a breaking change - clients must ignore unknown fields. Removing a field or changing its meaning gets a new API version with a deprecation notice at least 12 months ahead and a Sunset header on the old version. method_version values change independently of the API version and are never applied retroactively.

v1 hardening after the launch audit

· API version v1

109 audited defects processed. The OpenAPI document now declares every error response, all timestamps are RFC 3339 UTC, CAP POSTs require Idempotency-Key, webhook URLs are policy checked and secrets stored encrypted, SAR events are newest first, indices accept a quality filter, portfolios have a ranked parcel list - and more.

No field was removed and no meaning changed, so nothing on your side has to be updated; the items below are what you may notice.

Contract and documents

  • /v1/openapi.json declares the real error contract: every status an operation can return, with the shared ErrorEnvelope schema and error.type as an enum of the catalog; POSTs that answer 201/202 also declare the 200 of an idempotent replay. Generated SDKs no longer need a hand-written error path.
  • New error type method_not_allowed (405) - the catalog now has 34 types. validation_error rows name the field without a body./query. prefix.
  • Every timestamp (created_at, computed_at, issued_at, …) is UTC in RFC 3339 form with a Z suffix and is declared format: date-time.
  • x-agrovisio-lifecycle in the OpenAPI document and the Deprecation / Sunset / Link headers describe version retirement.
  • Security headers on every /v1 response; the API’s own HTML pages refuse to be framed.

Behaviour

  • Idempotency-Key is required on the CAP POSTs (/cap/subsidy/calculate, /cap/eco-schemes/optimize) as on every other POST. Concurrent requests with the same key answer 409 idempotency_conflict with detail.state: "in_progress" and Retry-After (at most 120 s). The key of a job stays bound to it for the job’s 180 day retention.
  • POST /v1/indices/batch answers 200 on the first call as well as on a replay (it was 201).
  • GET /v1/parcels/{id}/indices?quality= filters observations by class. Observations below 50 % valid pixels are cloud_masked with value: null (no undocumented poor class). Multi-year windows compare each observation with the norm of its own season.
  • GET /v1/parcels/{id}/sar/events returns events newest first.
  • GET /v1/portfolios/{id}/parcels: ranked, filterable parcel list for a portfolio.
  • GET /v1/jobs/{id}: eta_seconds counts down and is null when finished; attempts is reported; error is {type, message} with catalog types or timeout; failed attempts are retried after 30 s, 2 min and 10 min.
  • The four “no honest number” 422 responses (insufficient_data, baseline_not_ready, insufficient_resolution, vegetation_masked) carry the X-Agrovisio-Not-Billable header, as documented.
  • GET /v1/parcels and the portfolio list validate every filter and reject unknown query parameters (offset, misspelt filters) with 400 validation_error.
  • POST /v1/parcels derives country from the geometry and rejects a contradicting declared country; geometry repairs (unclosed ring, bow-tie) are reported in warnings, never applied silently.
  • Rate limit 429 caused by the per-second burst carries X-RateLimit-Burst-Limit / X-RateLimit-Burst-Reset; the minute headers keep describing the minute window.
  • Damage: an event_date whose 14 day post-event window has not closed is 400 date_range_invalid with detail.reason: post_window_open and detail.available_from.
  • Yield forecast: the confidence interval follows the growth phase of the requested season (with a +/-30 % emergence step and a harvested phase), and an unknown ?crop= is a 400 validation_error listing the supported codes.
  • CAP rotation: at most three consecutive seasons of the same crop; a fourth is a violation. Years are validated (four digits, 1990 to next year).

Webhooks

  • Endpoint URLs must be https://, at most 2048 characters, without credentials and on a public host; the check is repeated before every delivery and redirects are not followed.
  • Signing secrets are stored encrypted and shown once; an idempotent retry of the registration returns the same response.
  • Retry schedule 1 min, 5 min, 30 min, 2 h, 12 h (six attempts). An endpoint is disabled only when one delivery exhausts all attempts with no success in between; webhook.disabled goes to your other endpoints. New event type webhook.test for the portal’s test button.

Sandbox

  • The synthetic history is anchored to a fixed epoch, so demo results are stable across nightly reseeds. parcel_quota is 10 own parcels. Shared parcels carry shared: true for every key except the owning demo account.

v1 launch

· API version v1

First public version of the Data API - thirteen endpoint groups, one error envelope, sandbox with 20 seeded parcels, signed webhooks and generated SDKs.

The Data API is mounted at /v1 and documented by /v1/openapi.json (OpenAPI 3.1).

Endpoint groups

  • Account - GET /v1/account: plan, products, rate limits and current period usage.
  • Parcels - create from GeoJSON or cadastral number, bulk import (async), list with cursor pagination, delete; GET /v1/cadastre/lookup.
  • Indices - NDVI / NDWI / EVI series with per observation anomaly and five season baseline; latest; batch of up to 500 parcels.
  • Weather - 7 day forecast, daily history from 1981, agroclimate indicators per season.
  • SAR - Sentinel-1 backscatter series, detected events (lodging, mowing, harvest, tillage, regrowth), relative soil moisture.
  • Thermal - Sentinel-3 land surface temperature with anomaly, water stress index (parcels of 5 ha and more).
  • Yield - forecast with a mandatory confidence interval (/yield-forecast, alias /yield).
  • Damage - asynchronous before/after assessment, stored result, deterministic PDF certificate.
  • Risk - explainable 0-100 parcel score with six components, portfolio summary and refresh.
  • CAP - direct payment calculation, eco-scheme optimisation, rotation compliance.
  • Parametric Index - definitions (draft, publish, supersede), evaluation, backtest.
  • Jobs - polling for every 202 job.
  • Webhooks - subscriptions, event catalog, HMAC-SHA256 signed delivery with a 300 s replay window.

Conventions fixed at launch

  • Error envelope {error: {type, message, detail, request_id, doc_url}} with 33 stable error.type values.
  • Idempotency-Key required on every POST, stored for 24 hours, replays marked Idempotent-Replay: true.
  • Three rate limit pools (standard, write, expensive) with X-RateLimit-* headers on every response.
  • method_version and config_hash on every computed result; never changed retroactively.
  • X-Data-Attribution: Contains modified Copernicus Sentinel data on every satellite-derived response.

Tooling

  • Sandbox with 20 shared Lithuanian parcels and five years of history, rebuilt nightly, never billed.
  • Postman collection, static endpoint list and this documentation site are generated from the live OpenAPI document.
  • Python (agrovisio-data-api) and TypeScript (@agrovisio/data-api) SDKs generated from the same document.