{
  "openapi": "3.1.0",
  "info": {
    "title": "ZestLens API",
    "version": "1.0.0",
    "description": "Read-only access to your company's citrus measurements: blocks, weekly block summaries (diameter, EU size codes, weight, yield, peel defects, export grade, growth) and fruit-level measurements. Create an API key in the ZestLens app (Settings → API keys, administrators only) and send it as `Authorization: Bearer zlk_…`. Limit: 120 requests per minute per key. Text fields follow the `Accept-Language` header (en, es, pt, fr, it, de, el, tr, ar, ru, zh).",
    "contact": { "email": "info@zestlens.app", "url": "https://zestlens.app/developers" }
  },
  "servers": [{ "url": "https://api.zestlens.app" }],
  "security": [{ "apiKey": [] }],
  "components": {
    "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "zlk_…" } },
    "schemas": {
      "Block": { "type": "object", "properties": {
        "id": { "type": "integer" }, "name": { "type": "string" }, "cultivar": { "type": ["string", "null"] },
        "trees": { "type": ["integer", "null"] }, "area_ha": { "type": ["number", "null"] },
        "corners": { "type": ["array", "null"], "items": { "type": "array", "items": { "type": "number" }, "description": "[lat, lng]" } } } },
      "Fruit": { "type": "object", "properties": {
        "photo_id": { "type": "integer" }, "captured_at": { "type": "string", "format": "date-time" }, "block_id": { "type": ["integer", "null"] },
        "mode": { "type": "string", "enum": ["tree", "bin"] }, "sampling_point": { "type": ["string", "null"] },
        "lat": { "type": ["number", "null"] }, "lng": { "type": ["number", "null"] },
        "diameter_mm": { "type": "number" }, "size_code": { "type": ["string", "null"], "description": "EU 543/2011 size code" },
        "weight_g": { "type": ["number", "null"] }, "colour_stage": { "type": ["integer", "null"], "description": "1 dark green … 8 full orange" },
        "cci": { "type": ["number", "null"], "description": "Citrus colour index (Hunter Lab)" },
        "defect": { "type": ["object", "null"], "properties": {
          "severity": { "type": "string", "enum": ["none", "slight", "moderate", "serious", "severe"] }, "confirmed": { "type": "boolean" },
          "types": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } } } } },
        "distance_cm": { "type": ["number", "null"] }, "caliper_mm": { "type": ["number", "null"] },
        "scout": { "type": ["string", "null"] }, "picker": { "type": ["string", "null"] } } }
    }
  },
  "paths": {
    "/v1/blocks": { "get": { "summary": "List blocks", "responses": { "200": { "description": "Blocks",
      "content": { "application/json": { "schema": { "type": "object", "properties": { "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/Block" } } } } } } } } } },
    "/v1/blocks/{id}/summary": { "get": { "summary": "Weekly block summary",
      "description": "Latest week: photos, fruit measured, sampling points, diameter (mean, median, SD, 95% CI), 5 mm size distribution, EU size codes, mean weight, peel defect severity shares, export-grade share, colour stages; plus yield estimate, growth vs. reference curve, bin-scan stem quality, weekly history and analysis notes.",
      "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } },
        { "name": "mode", "in": "query", "schema": { "type": "string", "enum": ["tree", "bin"], "default": "tree" } }],
      "responses": { "200": { "description": "Summary" }, "404": { "description": "Block not found" } } } },
    "/v1/measurements": { "get": { "summary": "Fruit-level measurements (paged by photo id)",
      "parameters": [
        { "name": "block", "in": "query", "schema": { "type": "integer" } },
        { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } },
        { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } },
        { "name": "mode", "in": "query", "schema": { "type": "string", "enum": ["tree", "bin"] } },
        { "name": "limit", "in": "query", "description": "Photos per page (1–1000, default 200)", "schema": { "type": "integer" } },
        { "name": "after", "in": "query", "description": "Pass `next_after` from the previous page", "schema": { "type": "integer" } }],
      "responses": { "200": { "description": "Fruit",
        "content": { "application/json": { "schema": { "type": "object", "properties": {
          "fruit": { "type": "array", "items": { "$ref": "#/components/schemas/Fruit" } }, "next_after": { "type": ["integer", "null"] } } } } } } } } },
    "/v1/photos/{id}/control": { "get": { "summary": "Measurement image (fruit outline and diameter)",
      "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }],
      "responses": { "200": { "description": "JPEG", "content": { "image/jpeg": {} } } } } },
    "/v1/blocks/{id}/document": { "get": { "summary": "Full report document (A4 HTML with photos, tables, charts and literature)",
      "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } },
        { "name": "mode", "in": "query", "schema": { "type": "string", "enum": ["tree", "bin"] } }],
      "responses": { "200": { "description": "HTML", "content": { "text/html": {} } } } } }
  }
}