{ "openapi": "3.1.0", "info": { "title": "AgroReports API", "version": "0.1.0-beta", "description": "The report comes first. Generate reports, watch indices with threshold alerts, and read the field data underneath \u2014 over REST, with signed webhooks and full provenance. Public beta.", "contact": { "email": "contact@agroreports.org", "url": "https://www.agroreports.org/api/" } }, "servers": [ { "url": "https://api.agroreports.org", "description": "Production (public beta)" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Request a key through https://www.agroreports.org/api/#access" } }, "schemas": { "Geometry": { "oneOf": [ { "type": "object", "required": [ "type", "coordinates" ], "properties": { "type": { "const": "Polygon" }, "coordinates": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "type": "number" } } } } } }, { "type": "object", "required": [ "west", "south", "east", "north" ], "properties": { "west": { "type": "number" }, "south": { "type": "number" }, "east": { "type": "number" }, "north": { "type": "number" } } } ] }, "Provenance": { "type": "object", "required": [ "area_ha", "resolution_m", "method_version", "caveat" ], "properties": { "area_ha": { "type": "number" }, "resolution_m": { "type": "integer" }, "method_version": { "type": "string" }, "caveat": { "type": "string" } } }, "Scene": { "type": "object", "required": [ "date", "source", "cloud_pct", "valid_px" ], "properties": { "date": { "type": "string", "format": "date" }, "source": { "type": "string", "examples": [ "sentinel-2-l2a", "landsat-8", "landsat-9" ] }, "cloud_pct": { "type": "number", "minimum": 0, "maximum": 100 }, "valid_px": { "type": "number", "minimum": 0, "maximum": 1 } } }, "Error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "INVALID_GEOMETRY", "AREA_TOO_LARGE", "NO_CLEAR_SCENE", "RATE_LIMITED", "QUOTA_EXHAUSTED", "REPORT_DISABLED", "NOT_FOUND", "UPSTREAM_TIMEOUT", "UPSTREAM_ERROR", "INVALID_INPUT" ] }, "message": { "type": "string" }, "next": { "type": "string" } } }, "Report": { "type": "object", "required": [ "report", "type", "status", "field", "summary", "artifacts", "provenance" ], "properties": { "report": { "type": "string", "examples": [ "rep_champagne_07" ] }, "type": { "type": "string", "examples": [ "vineyard-performance" ] }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed" ] }, "field": { "type": "object", "properties": { "name": { "type": "string" }, "area_ha": { "type": "number" } } }, "scene": { "$ref": "#/components/schemas/Scene" }, "summary": { "type": "string" }, "severity": { "type": "string", "enum": [ "ok", "watch", "alert" ] }, "actions": { "type": "array", "items": { "type": "string" } }, "risk": { "type": "string" }, "artifacts": { "type": "object", "properties": { "pdf": { "type": "string", "format": "uri" }, "csv": { "type": "string", "format": "uri" } } }, "provenance": { "$ref": "#/components/schemas/Provenance" } } }, "AlertRule": { "type": "object", "required": [ "id", "field", "index", "condition", "threshold", "window", "channels", "status" ], "properties": { "id": { "type": "string", "examples": [ "alr_champagne_07" ] }, "field": { "type": "string", "examples": [ "fld_champagne_07" ] }, "index": { "type": "string", "enum": [ "ndvi", "ndmi", "nbr", "ndre", "ndwi" ] }, "condition": { "type": "string", "enum": [ "below", "above" ] }, "threshold": { "type": "number" }, "window": { "type": "object", "required": [ "start", "end" ], "properties": { "start": { "type": "string", "format": "date" }, "end": { "type": "string", "format": "date" } } }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "dashboard", "email", "webhook", "whatsapp", "telegram" ] } }, "webhook_url": { "type": "string", "format": "uri" }, "status": { "type": "string", "enum": [ "armed", "paused" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "AlertEvent": { "type": "object", "required": [ "id", "alert_id", "date", "index", "value", "threshold", "scene" ], "properties": { "id": { "type": "string" }, "alert_id": { "type": "string" }, "date": { "type": "string", "format": "date-time" }, "index": { "type": "string" }, "value": { "type": "number" }, "threshold": { "type": "number" }, "message": { "type": "string" }, "scene": { "$ref": "#/components/schemas/Scene" }, "delivered": { "type": "array", "items": { "type": "string" } } } } } }, "paths": { "/v1/reports/types": { "get": { "summary": "List the eight report types", "operationId": "list_report_types", "x-mcp-tool": "list_report_types", "responses": { "200": { "description": "Report types with indices, timeframe and description." } } } }, "/v1/reports": { "post": { "summary": "Start an asynchronous field report", "operationId": "generate_report", "x-mcp-tool": "generate_report", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "geometry", "reportType" ], "properties": { "geometry": { "$ref": "#/components/schemas/Geometry" }, "reportType": { "type": "string" }, "lang": { "type": "string", "enum": [ "en", "fr", "es", "pt", "de" ], "default": "en" }, "fireDate": { "type": "string", "format": "date" } } } } } }, "responses": { "202": { "description": "Report queued. Poll the status URL.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "status_url" ], "properties": { "id": { "type": "string" }, "status_url": { "type": "string", "format": "uri" } } } } } } } } }, "/v1/reports/{id}": { "get": { "summary": "Poll a report and read the result", "operationId": "get_report", "x-mcp-tool": "get_report", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The report, its summary, PDF/CSV links and provenance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Report" } } } } } } }, "/v1/alerts": { "post": { "summary": "Create a threshold alert rule", "operationId": "create_alert", "x-mcp-tool": "create_alert", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertRule" } } } }, "responses": { "201": { "description": "Rule armed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertRule" } } } } } }, "get": { "summary": "List alert rules", "operationId": "list_alerts", "x-mcp-tool": "list_alerts", "responses": { "200": { "description": "Rules with status and last event.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AlertRule" } } } } } } } }, "/v1/alerts/{id}": { "get": { "summary": "Get an alert rule", "operationId": "get_alert", "x-mcp-tool": "list_alerts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The rule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertRule" } } } } } }, "patch": { "summary": "Update threshold, window, channels or status", "operationId": "update_alert", "x-mcp-tool": "update_alert", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertRule" } } } }, "responses": { "200": { "description": "Updated rule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertRule" } } } } } }, "delete": { "summary": "Delete an alert rule", "operationId": "delete_alert", "x-mcp-tool": "update_alert", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." } } } }, "/v1/alerts/{id}/events": { "get": { "summary": "List triggered alert events", "operationId": "get_alert_events", "x-mcp-tool": "get_alert_events", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Events with index, value, scene and delivery channels.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AlertEvent" } } } } } } } }, "/v1/indices": { "get": { "summary": "List the eight indices", "operationId": "list_indices", "x-mcp-tool": "list_indices", "responses": { "200": { "description": "Index catalog with formula, bands, range, thresholds and use." } } } }, "/v1/indices/query": { "post": { "summary": "Current index values for a field", "operationId": "get_indices", "x-mcp-tool": "get_indices", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "geometry", "indices" ], "properties": { "geometry": { "$ref": "#/components/schemas/Geometry" }, "indices": { "type": "array", "items": { "type": "string" }, "maxItems": 8 }, "date": { "type": "string", "format": "date" }, "windowDays": { "type": "integer", "minimum": 1, "maximum": 180, "default": 30 } } } } } }, "responses": { "200": { "description": "Field record with scene, indices, provenance and caveat.", "content": { "application/json": { "schema": { "type": "object", "required": [ "field", "scene", "indices", "provenance" ], "properties": { "field": { "type": "string" }, "scene": { "$ref": "#/components/schemas/Scene" }, "indices": { "type": "object", "additionalProperties": { "type": "number" } }, "provenance": { "$ref": "#/components/schemas/Provenance" } } } } } }, "400": { "description": "Invalid geometry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Area too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate or quota limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/indices/timeseries": { "post": { "summary": "Index history for a field", "operationId": "get_index_timeseries", "x-mcp-tool": "get_index_timeseries", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "geometry", "indices", "startDate" ], "properties": { "geometry": { "$ref": "#/components/schemas/Geometry" }, "indices": { "type": "array", "items": { "type": "string" } }, "startDate": { "type": "string", "format": "date" }, "endDate": { "type": "string", "format": "date" } } } } } }, "responses": { "200": { "description": "Periods with index values, scene dates and valid-pixel share." } } } }, "/v1/indices/burn-severity": { "post": { "summary": "dNBR and USGS burn-severity class", "operationId": "compute_burn_severity", "x-mcp-tool": "compute_burn_severity", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "geometry", "fireDate" ], "properties": { "geometry": { "$ref": "#/components/schemas/Geometry" }, "fireDate": { "type": "string", "format": "date" } } } } } }, "responses": { "200": { "description": "Pre-fire NBR, post-fire NBR, dNBR, severity class and map tiles." } } } }, "/v1/location": { "get": { "summary": "Resolve a place name or coordinate to a bounding box", "operationId": "find_location", "x-mcp-tool": "find_location", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "lat", "in": "query", "schema": { "type": "number" } }, { "name": "lon", "in": "query", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Resolved name, bounding box and centroid." } } } } } }