{
  "openapi": "3.1.0",
  "info": {
    "title": "Balcones Apiary Co.",
    "version": "1",
    "description": "Prepare a preliminary tract plan and request managed hive placement, ongoing care and district documentation. Unknown acreage, history or timing may remain open. Balcones evaluates district rules and site needs, seeks placement options and replies by email with feasibility, scope and proposed written terms. A successful submission gives a reference, not approval, booking or an order."
  },
  "servers": [
    {
      "url": "https://balconesapiary.forevenza.com"
    }
  ],
  "paths": {
    "/_c/request": {
      "post": {
        "operationId": "submit_request",
        "summary": "Send a requirement to Balcones Apiary Co.",
        "description": "A successful submission is recorded with a reference number. When an address is left, Balcones Apiary Co. replies by email. Balcones evaluates district rules, eligible area, history and site needs, seeks placement options and prepares feasibility, a management and documentation scope and proposed written terms. Nothing is ordered or committed until the owner agrees terms. Contact details are kept apart from the requirement, while we correspond or do business and for 24 months after, so a later request picks up where it left off; ask us to delete them at any time.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "need"
                ],
                "properties": {
                  "action": {
                    "type": "string",
                    "enum": [
                      "buy",
                      "source",
                      "quote",
                      "verify",
                      "lease",
                      "license",
                      "hire",
                      "retrieve",
                      "convert",
                      "other"
                    ],
                    "description": "What you want done"
                  },
                  "need": {
                    "type": "string",
                    "maxLength": 2000,
                    "description": "The requirement in your own words"
                  },
                  "specifications": {
                    "type": "object",
                    "properties": {
                      "county": {
                        "type": "string",
                        "description": "Texas county, unresolved if not supplied",
                        "x-facet": "geography"
                      },
                      "gross_acres": {
                        "type": "number",
                        "minimum": 0.1,
                        "maximum": 200,
                        "description": "Gross deed acreage, not automatically eligible area",
                        "x-facet": "quantity"
                      },
                      "house": {
                        "type": "string",
                        "description": "Owner states house or planned house yes or no",
                        "x-facet": "specification"
                      },
                      "homesite_acres": {
                        "type": "number",
                        "minimum": 0,
                        "description": "Known owner-stated homesite area, omitted when unknown; no default deduction",
                        "x-facet": "quantity"
                      },
                      "eligible_acres": {
                        "type": "number",
                        "minimum": 0,
                        "description": "Owner-stated eligible or proposed area in no-script intake; district review pending",
                        "x-facet": "quantity"
                      },
                      "qualifying_acres": {
                        "type": "number",
                        "minimum": 0,
                        "description": "Owner-stated eligible or proposed beekeeping area, not a district determination",
                        "x-facet": "quantity"
                      },
                      "valuation_status": {
                        "type": "string",
                        "description": "ag_other, ag_bees, building, history, none, wildlife or unsure; market value does not establish absent history",
                        "x-facet": "specification"
                      },
                      "needed_by": {
                        "type": "string",
                        "description": "Preferred YYYY-MM month, not a confirmed or precise placement date; timing may remain open",
                        "x-facet": "timing"
                      },
                      "needed_month": {
                        "type": "string",
                        "description": "Preferred month in no-script intake",
                        "x-facet": "timing"
                      },
                      "needed_year": {
                        "type": "string",
                        "description": "Preferred year in no-script intake",
                        "x-facet": "timing"
                      },
                      "truck_access": {
                        "type": "string",
                        "description": "yes, no or unsure; not a blocker to review",
                        "x-facet": "specification"
                      },
                      "water": {
                        "type": "string",
                        "description": "yes, no or unsure",
                        "x-facet": "specification"
                      },
                      "property_id": {
                        "type": "string",
                        "maxLength": 80,
                        "description": "District property ID, optional",
                        "x-facet": "identifier"
                      },
                      "note": {
                        "type": "string",
                        "maxLength": 4000,
                        "description": "Full buyer context, prior use, timing preferences, lease end, site details and missing records",
                        "x-facet": "specification"
                      },
                      "current_use_ending": {
                        "type": "boolean",
                        "description": "Current use or beekeeper is ending or has left",
                        "x-facet": "timing"
                      },
                      "time_sensitive": {
                        "type": "boolean",
                        "description": "Preliminary urgency from timing, use ending or reported survey date",
                        "x-facet": "timing"
                      },
                      "urgency_reasons": {
                        "type": "array",
                        "description": "Context supporting preliminary urgency",
                        "x-facet": "timing",
                        "items": {
                          "type": "string"
                        }
                      },
                      "open_questions": {
                        "type": "array",
                        "description": "Unresolved facts and next work owned by Balcones or owner",
                        "x-facet": "specification",
                        "items": {
                          "type": "string"
                        }
                      },
                      "documentation_wanted": {
                        "type": "array",
                        "description": "Desired records, agreement, registration, filing support and applicable county additions",
                        "x-facet": "specification",
                        "items": {
                          "type": "string"
                        }
                      },
                      "proposed_scope": {
                        "type": "string",
                        "description": "Preliminary management and sourcing scope to progress by email",
                        "x-facet": "specification"
                      },
                      "timing_summary": {
                        "type": "string",
                        "description": "Editable interpretation of owner timing, including exact deadlines, ASAP or seasons; a preference not a booking",
                        "x-facet": "timing"
                      },
                      "preferred_placement": {
                        "type": "string",
                        "description": "Owner's preferred placement month, season or date, distinct from departure and latest acceptable date; not confirmed",
                        "x-facet": "timing"
                      },
                      "placement_deadline": {
                        "type": "string",
                        "description": "Owner's latest acceptable placement date, separately retained from the preference; original language in timing_summary and note",
                        "x-facet": "timing"
                      },
                      "timing_revision_history": {
                        "type": "array",
                        "description": "Explicit owner preference updates; original wording remains in note",
                        "x-facet": "timing",
                        "items": {
                          "type": "string"
                        }
                      },
                      "timing_source_superseded": {
                        "type": "boolean",
                        "description": "Owner explicitly replaced source timing with the current preference; no placement confirmation",
                        "x-facet": "timing"
                      },
                      "continuity_summary": {
                        "type": "string",
                        "description": "Editable chronology and evidence-gap work, distinguishing past departure from a future lease ending",
                        "x-facet": "specification"
                      },
                      "documentation_provenance": {
                        "type": "string",
                        "description": "Balcones recommended core, conditional county additions and owner edits; applicability unresolved until district review",
                        "x-facet": "specification"
                      },
                      "assessment": {
                        "type": "string",
                        "description": "Preliminary route and source-labelled uncertainties, not district approval",
                        "x-facet": "specification"
                      },
                      "history_review": {
                        "type": "string",
                        "description": "Original selection and conflicting situation preserved for district review",
                        "x-facet": "specification"
                      },
                      "history_resolution": {
                        "type": "string",
                        "description": "Owner choice: provisional existing-history review or unresolved review",
                        "x-facet": "specification"
                      },
                      "site_context": {
                        "type": "object",
                        "description": "Separate selections distinguished from facts reported in the original situation",
                        "x-facet": "specification"
                      },
                      "supersedes_reference": {
                        "type": "string",
                        "description": "Prior request reference this revised requirement asks Balcones to supersede; not a status confirmation",
                        "x-facet": "identifier"
                      }
                    },
                    "description": "Details you already know. The business helps resolve missing specifications in the continuing engagement."
                  },
                  "quantity": {
                    "type": "object",
                    "properties": {
                      "amount": {
                        "type": "number"
                      },
                      "unit": {
                        "type": "string"
                      },
                      "per": {
                        "type": "string"
                      }
                    }
                  },
                  "timing": {
                    "type": "object",
                    "properties": {
                      "earliest": {
                        "type": "string"
                      },
                      "latest": {
                        "type": "string"
                      },
                      "recurrence": {
                        "type": "string"
                      },
                      "text": {
                        "type": "string"
                      }
                    }
                  },
                  "geography": {
                    "type": "object",
                    "properties": {
                      "text": {
                        "type": "string"
                      },
                      "country": {
                        "type": "string"
                      },
                      "from": {
                        "type": "string"
                      },
                      "to": {
                        "type": "string"
                      }
                    }
                  },
                  "budget": {
                    "type": "object",
                    "properties": {
                      "amount": {
                        "type": "number"
                      },
                      "currency": {
                        "type": "string",
                        "description": "ISO 4217, default USD"
                      },
                      "per": {
                        "type": "string",
                        "description": "total, unit, month, year, load, ..."
                      }
                    }
                  },
                  "requested_fields": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "maxItems": 30,
                    "description": "Result fields you need"
                  },
                  "contact": {
                    "type": "object",
                    "description": "Optional; stored apart from the requirement, kept while we correspond or do business and for 24 months after, then deleted; you can ask us to delete it sooner",
                    "properties": {
                      "email": {
                        "type": "string"
                      },
                      "name": {
                        "type": "string"
                      },
                      "organization": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Recorded, with a reference number"
          },
          "400": {
            "description": "What to fix"
          }
        }
      }
    }
  }
}