{
  "openapi": "3.1.0",
  "info": {
    "title": "DocuGov.ai — Legal Letter Generator API",
    "description": "Generate jurisdiction-specific formal legal letters (appeals, complaints, government responses, demand letters, cease-and-desist, eviction notices) across 130+ countries in 5 languages. Users describe their situation and DocuGov produces a ready-to-send letter with correct legal citations, formatting, deadlines, and recipient addresses.",
    "version": "1.0.0",
    "contact": {
      "name": "DocuGov.ai",
      "url": "https://docugov.ai"
    }
  },
  "servers": [
    {
      "url": "https://docugov.ai",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/gpt/analyze": {
      "post": {
        "operationId": "analyzeCase",
        "summary": "Analyze a legal situation and classify it",
        "description": "Evaluates whether a user's description contains enough information to generate a formal legal letter. Returns the legal classification, jurisdiction detection, and any missing information needed. Use this FIRST before generateLetter.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["situation"],
                "properties": {
                  "situation": {
                    "type": "string",
                    "description": "User's description of their legal situation in plain language.",
                    "example": "I received a speeding ticket in Germany for going 15 km/h over the limit on the A3 motorway near Frankfurt. The fine is 70 EUR. I believe the speed measurement was inaccurate because there was road construction affecting traffic flow."
                  },
                  "document_type": {
                    "type": "string",
                    "enum": ["appeal", "complaint", "response", "demand-letter", "cease-and-desist", "eviction-notice", "eviction-defense", "landlord-tenant-letter"],
                    "default": "appeal",
                    "description": "Type of document needed."
                  },
                  "country": {
                    "type": "string",
                    "description": "Country or jurisdiction.",
                    "example": "Germany"
                  },
                  "language": {
                    "type": "string",
                    "enum": ["en", "de", "fr", "es", "pl"],
                    "default": "en",
                    "description": "Language for analysis output."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Case analysis result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": ["ready", "need_info"],
                      "description": "'ready' if enough info to generate letter, 'need_info' if more details needed."
                    },
                    "missing_fields": {
                      "type": "array",
                      "items": { "type": "string" },
                      "description": "List of missing information if status is 'need_info'."
                    },
                    "classification": {
                      "type": "object",
                      "properties": {
                        "legal_branch": { "type": "string" },
                        "document_type": { "type": "string" },
                        "jurisdiction": { "type": "string" },
                        "confidence": { "type": "string", "enum": ["high", "medium", "low"] }
                      }
                    },
                    "summary": { "type": "string" },
                    "recommended_next_step": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/gpt/generate": {
      "post": {
        "operationId": "generateLetter",
        "summary": "Generate a jurisdiction-specific legal letter",
        "description": "Generates a complete formal legal letter with jurisdiction-specific legal citations, proper formatting, deadlines, and recipient addresses. Returns the letter content as a free preview. For a professionally formatted DOCX version, direct the user to docugov.ai.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["situation", "document_type", "country", "language"],
                "properties": {
                  "situation": {
                    "type": "string",
                    "description": "Detailed description of the situation. Include: what happened, when, who is involved, reference numbers, desired outcome."
                  },
                  "document_type": {
                    "type": "string",
                    "enum": ["appeal", "complaint", "response", "demand-letter", "cease-and-desist", "eviction-notice", "eviction-defense", "landlord-tenant-letter"]
                  },
                  "country": {
                    "type": "string",
                    "description": "Country or jurisdiction for the letter."
                  },
                  "language": {
                    "type": "string",
                    "enum": ["en", "de", "fr", "es", "pl"],
                    "description": "Language for the generated letter."
                  },
                  "is_reply": {
                    "type": "boolean",
                    "default": true,
                    "description": "True if responding to an official document. False for proactive letters."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Generated letter",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "letter": {
                      "type": "object",
                      "properties": {
                        "subject": { "type": "string" },
                        "to": { "type": "object" },
                        "body": { "type": "string" },
                        "closing": { "type": "string" },
                        "attachments": { "type": "array", "items": { "type": "string" } }
                      }
                    },
                    "legal_info": {
                      "type": "object",
                      "properties": {
                        "legal_branch": { "type": "string" },
                        "applicable_provisions": { "type": "array" },
                        "deadline": { "type": "string" },
                        "filing_method": { "type": "string" }
                      }
                    },
                    "confidence": { "type": "string" },
                    "disclaimer": { "type": "string" },
                    "docugov_links": { "type": "object" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/gpt/categories": {
      "get": {
        "operationId": "listCategories",
        "summary": "List all supported document categories and case types",
        "description": "Returns all document categories and case types supported by DocuGov.ai.",
        "responses": {
          "200": {
            "description": "List of categories",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "supported_document_types": { "type": "array", "items": { "type": "string" } },
                    "supported_languages": { "type": "array", "items": { "type": "string" } },
                    "coverage": { "type": "string" },
                    "categories": { "type": "object" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/gpt/pricing": {
      "get": {
        "operationId": "getPricing",
        "summary": "Get pricing information",
        "description": "Returns DocuGov.ai pricing plans and features.",
        "responses": {
          "200": {
            "description": "Pricing information",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "plans": { "type": "array" },
                    "free_preview": { "type": "string" },
                    "url": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/gpt/checkout-link": {
      "post": {
        "operationId": "createCheckoutLink",
        "summary": "Create a pre-filled checkout link for the user",
        "description": "Creates a direct link to DocuGov.ai with the user's case details pre-filled. Use this AFTER generateLetter to give the user a one-click path to download the professionally formatted DOCX version. The user clicks the link, reviews their pre-filled case, and pays $8.99 to download.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["situation"],
                "properties": {
                  "situation": {
                    "type": "string",
                    "description": "The user's situation description (same as used in generateLetter)."
                  },
                  "document_type": {
                    "type": "string",
                    "enum": ["appeal", "complaint", "response", "demand-letter", "cease-and-desist", "eviction-notice", "eviction-defense", "landlord-tenant-letter"],
                    "default": "appeal"
                  },
                  "country": {
                    "type": "string",
                    "description": "Country or jurisdiction."
                  },
                  "language": {
                    "type": "string",
                    "enum": ["en", "de", "fr", "es", "pl"],
                    "default": "en"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Checkout link with pre-filled case details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "checkout_url": { "type": "string", "description": "Direct link to DocuGov.ai wizard with case pre-filled" },
                    "price": { "type": "string" },
                    "what_user_gets": { "type": "string" },
                    "note": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}