{
  "openapi": "3.1.0",
  "info": {
    "title": "Louisville Clean Guide request API",
    "version": "1.0.0",
    "description": "HTTP access for user-authorized agents; no computer use, account or API key required. Read service status first. Preserve the standard CSRF cookie/header and same-origin header. Messages are unmonitored during the pilot."
  },
  "servers": [
    {
      "url": "https://louisvillecleanguide.com"
    }
  ],
  "paths": {
    "/service.json": {
      "get": {
        "operationId": "getServiceInfo",
        "summary": "Read status before sending",
        "responses": {
          "200": {
            "description": "Current service and contact availability.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/csrf/": {
      "get": {
        "operationId": "getRequestSession",
        "description": "Fetch first with an HTTP cookie jar. Preserve the csrftoken Set-Cookie and send csrfToken as X-CSRFToken on POST. This is Django’s standard CSRF protection, not a login or API key.",
        "responses": {
          "200": {
            "description": "Session token and cookie.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "csrfToken"
                  ],
                  "properties": {
                    "csrfToken": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "headers": {
              "Set-Cookie": {
                "schema": {
                  "type": "string"
                },
                "description": "csrftoken cookie; preserve in your HTTP session."
              }
            }
          }
        }
      }
    },
    "/api/inquiries/louisville/": {
      "post": {
        "operationId": "requestService",
        "summary": "Save an authorized inquiry",
        "description": "Read /service.json first. Do not submit without the user’s permission. A saved record does not contact a provider, book service or promise a reply. On timeout, retry with the same client_id and identical payload; do not create a new UUID.",
        "security": [
          {
            "csrfCookie": [],
            "csrfHeader": []
          }
        ],
        "parameters": [
          {
            "name": "Origin",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Exact API site origin, for example https://louisvillecleanguide.com. No browser is required."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "client_id"
                ],
                "properties": {
                  "client_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Generate once per operation. Retry an uncertain response with this same UUID and identical payload."
                  },
                  "message": {
                    "type": "string",
                    "maxLength": 6000,
                    "default": ""
                  },
                  "brief": {
                    "type": "array",
                    "maxItems": 80,
                    "default": [],
                    "items": {
                      "type": "object",
                      "required": [
                        "name",
                        "value"
                      ],
                      "properties": {
                        "name": {
                          "type": "string",
                          "maxLength": 80
                        },
                        "value": {
                          "type": "string",
                          "maxLength": 1000
                        },
                        "checked": {
                          "type": "boolean"
                        }
                      }
                    }
                  },
                  "email": {
                    "type": "string",
                    "maxLength": 254,
                    "description": "One valid reply email OR phone is sufficient, even if the other is blank or invalid."
                  },
                  "phone": {
                    "type": "string",
                    "maxLength": 40,
                    "description": "Optional if email is valid; US numbers accepted."
                  },
                  "source_path": {
                    "type": "string",
                    "default": "/",
                    "pattern": "^/[^?#]*$",
                    "maxLength": 200
                  },
                  "submission_method": {
                    "type": "string",
                    "enum": [
                      "browser",
                      "webmcp",
                      "http_api"
                    ],
                    "default": "http_api"
                  }
                },
                "anyOf": [
                  {
                    "required": [
                      "email"
                    ]
                  },
                  {
                    "required": [
                      "phone"
                    ]
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Saved.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "id",
                    "update_token",
                    "is_test"
                  ],
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "update_token": {
                      "type": "string",
                      "description": "Private signed update capability, valid for 24 hours. Keep it out of URLs, logs and messages."
                    },
                    "is_test": {
                      "type": "boolean",
                      "description": "True means stored as a test/pilot record, not a production lead."
                    }
                  }
                }
              }
            }
          },
          "200": {
            "description": "Already saved; safe retry.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "id",
                    "update_token",
                    "is_test"
                  ],
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "update_token": {
                      "type": "string",
                      "description": "Private signed update capability, valid for 24 hours. Keep it out of URLs, logs and messages."
                    },
                    "is_test": {
                      "type": "boolean",
                      "description": "True means stored as a test/pilot record, not a production lead."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid reply details, payload or reused UUID with different data."
          },
          "403": {
            "description": "Origin, CSRF or update token refused."
          },
          "404": {
            "description": "Unknown inquiry/site."
          },
          "413": {
            "description": "Body exceeds 64 KiB."
          },
          "429": {
            "description": "Throttled; wait before retrying."
          },
          "503": {
            "description": "Unavailable; outcome may be uncertain, preserve retry UUID."
          }
        }
      }
    },
    "/api/inquiries/louisville/{id}/addenda/": {
      "post": {
        "operationId": "addRequestDetails",
        "summary": "Add optional details to the same inquiry",
        "description": "Read /service.json first. Do not submit without the user’s permission. A saved record does not contact a provider, book service or promise a reply. On timeout, retry with the same client_id and identical payload; do not create a new UUID.",
        "security": [
          {
            "csrfCookie": [],
            "csrfHeader": []
          }
        ],
        "parameters": [
          {
            "name": "Origin",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Exact API site origin, for example https://louisvillecleanguide.com. No browser is required."
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "X-Inquiry-Token",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Private update_token from the saved receipt."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "client_id"
                ],
                "properties": {
                  "client_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Generate once per operation. Retry an uncertain response with this same UUID and identical payload."
                  },
                  "message": {
                    "type": "string",
                    "maxLength": 6000,
                    "default": ""
                  },
                  "brief": {
                    "type": "array",
                    "maxItems": 80,
                    "default": [],
                    "items": {
                      "type": "object",
                      "required": [
                        "name",
                        "value"
                      ],
                      "properties": {
                        "name": {
                          "type": "string",
                          "maxLength": 80
                        },
                        "value": {
                          "type": "string",
                          "maxLength": 1000
                        },
                        "checked": {
                          "type": "boolean"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Saved.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "id",
                    "addendum_id"
                  ],
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "addendum_id": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "200": {
            "description": "Already saved; safe retry.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "id",
                    "addendum_id"
                  ],
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "addendum_id": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid reply details, payload or reused UUID with different data."
          },
          "403": {
            "description": "Origin, CSRF or update token refused."
          },
          "404": {
            "description": "Unknown inquiry/site."
          },
          "413": {
            "description": "Body exceeds 64 KiB."
          },
          "429": {
            "description": "Throttled; wait before retrying."
          },
          "503": {
            "description": "Unavailable; outcome may be uncertain, preserve retry UUID."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "csrfCookie": {
        "type": "apiKey",
        "in": "cookie",
        "name": "csrftoken"
      },
      "csrfHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-CSRFToken"
      }
    }
  }
}
