{
  "openapi": "3.1.0",
  "info": {
    "title": "The Local Upgrade - Free bid and business inquiry intake",
    "version": "1.0.0",
    "description": "Authorized agent submissions for human review. No payment, automated quote or development commitment. See /agents.txt."
  },
  "servers": [
    {
      "url": "https://thelocalupgrade.com"
    }
  ],
  "paths": {
    "/api/software-planner/agent-request": {
      "post": {
        "operationId": "requestSoftwareBidOrInformation",
        "summary": "Submit a free bid request or a question for email follow-up",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "requestId",
                  "agent",
                  "contact",
                  "brief",
                  "consent"
                ],
                "properties": {
                  "requestId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "UUID v4, retained for identical retries"
                  },
                  "intent": {
                    "type": "string",
                    "enum": [
                      "bid",
                      "inquiry"
                    ],
                    "default": "bid"
                  },
                  "agent": {
                    "type": "object",
                    "required": [
                      "name",
                      "authorizedByRequester"
                    ],
                    "properties": {
                      "name": {
                        "type": "string",
                        "maxLength": 120,
                        "minLength": 1
                      },
                      "authorizedByRequester": {
                        "const": true
                      }
                    }
                  },
                  "contact": {
                    "type": "object",
                    "required": [
                      "name",
                      "email",
                      "business"
                    ],
                    "properties": {
                      "name": {
                        "type": "string",
                        "maxLength": 120,
                        "minLength": 1
                      },
                      "email": {
                        "type": "string",
                        "maxLength": 254,
                        "format": "email"
                      },
                      "business": {
                        "type": "string",
                        "maxLength": 160
                      }
                    }
                  },
                  "brief": {
                    "type": "string",
                    "maxLength": 120000,
                    "description": "Bid: 80+ trimmed characters unless attachment. Inquiry: 20-5000 characters, no attachment."
                  },
                  "setup": {
                    "type": [
                      "object",
                      "null"
                    ],
                    "description": "Usually omit or null. Optional fields project, problem, users, existing, constraints; see human planner."
                  },
                  "attachment": {
                    "type": [
                      "object",
                      "null"
                    ],
                    "properties": {
                      "name": {
                        "type": "string",
                        "maxLength": 160
                      },
                      "type": {
                        "type": "string"
                      },
                      "base64": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "name",
                      "type",
                      "base64"
                    ]
                  },
                  "consent": {
                    "const": true
                  },
                  "website": {
                    "type": "string",
                    "const": ""
                  }
                }
              },
              "example": {
                "requestId": "c2f05113-928e-4e04-8643-a4234a350736",
                "intent": "bid",
                "agent": {
                  "name": "Your agent name",
                  "authorizedByRequester": true
                },
                "contact": {
                  "name": "Authorized requester",
                  "email": "requester@example.com",
                  "business": "Example business"
                },
                "setup": null,
                "brief": "We need a customer inquiry form on an existing website. Send inquiries to staff, prevent duplicate submissions, and display a receipt. Budget and deadline are not yet confirmed.",
                "attachment": null,
                "consent": true,
                "website": ""
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Identical request already saved"
          },
          "201": {
            "description": "Saved: success, reference, status received, paid false"
          },
          "400": {
            "description": "Validation or authorization declaration error"
          },
          "403": {
            "description": "Browser origin rejected"
          },
          "409": {
            "description": "Request ID already used with different content"
          },
          "413": {
            "description": "Request exceeds 3000000 bytes"
          },
          "415": {
            "description": "application/json required"
          },
          "429": {
            "description": "Shared email or IP rate limit"
          },
          "503": {
            "description": "Storage receipt not confirmed; bounded retry with same ID and payload"
          }
        }
      }
    }
  }
}