{
  "openapi": "3.0.3",
  "info": {
    "title": "Forms Legal Public API",
    "description": "Live, key-free, CORS-open endpoints for AI agents, academic researchers, and programmatic clients. Search 19,000+ free, statute-referenced legal document templates across 36 jurisdictions, and generate one-click academic citations for any Forms Legal page. Reference templates only — not legal advice.",
    "version": "1.0.0",
    "contact": {
      "name": "Forms Legal",
      "url": "https://forms-legal.com",
      "email": "support@forms-legal.com"
    },
    "license": {
      "name": "Reference templates — not legal advice",
      "url": "https://forms-legal.com/terms"
    }
  },
  "servers": [
    {
      "url": "https://forms-legal.com",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/search-docs": {
      "get": {
        "operationId": "searchDocs",
        "summary": "Search legal document templates",
        "description": "Lightweight, ranked document search intended for LLM/AI agents and programmatic clients. Returns a small set of matching V2 templates with canonical absolute URLs so a model can cite a specific document directly. Only indexable documents are returned. By default a document of a native-language jurisdiction (for example Spain, Mexico, Brazil, France, Italy, Poland) comes back with its own title, summary and slug, the same words its canonical page shows; add lang=en to get an English title, summary and jurisdiction for every document (url and slug unchanged). This is not the full index dump.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Search query (2–80 characters). Whitespace-separated terms are matched against template title, slug, category, subcategory, and country.",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 80
            },
            "example": "non-disclosure agreement"
          },
          {
            "name": "country",
            "in": "query",
            "required": false,
            "description": "Restrict results to a single jurisdiction by its country slug (e.g. usa, uk, canada, hong-kong, austria, espana, brasil, italy, polska).",
            "schema": {
              "type": "string",
              "maxLength": 40
            },
            "example": "usa"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of results to return (1–50).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 15
            },
            "example": 10
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "Language of the title, summary and jurisdiction fields; url and slug always stay the canonical native-language ones. Omit it to get each document in the native language of its jurisdiction (English for English-speaking jurisdictions). A supported locale code asks for that language for every document and falls back to English where the document has none; an unsupported code is ignored and the response reports lang as \"native\". lang=en forces English title, summary and jurisdiction for all documents (url and slug unchanged).",
            "schema": {
              "type": "string",
              "enum": ["en", "es", "pt", "de", "fr", "it", "nl", "sv", "nb", "fi", "da", "pl"]
            },
            "example": "en"
          }
        ],
        "responses": {
          "200": {
            "description": "Ranked search results.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                },
                "example": {
                  "query": "non-disclosure agreement",
                  "country": "usa",
                  "lang": "native",
                  "count": 1,
                  "results": [
                    {
                      "title": "Non-Disclosure Agreement",
                      "url": "https://forms-legal.com/usa/business/contracts/non-disclosure-agreement",
                      "country": "usa",
                      "category": "business",
                      "subcategory": "contracts",
                      "jurisdiction": "Uniform Trade Secrets Act",
                      "summary": "Free mutual non-disclosure agreement template aligned with US state confidentiality law.",
                      "language": "en",
                      "slug": "non-disclosure-agreement"
                    }
                  ],
                  "note": "Forms Legal provides free statute-referenced reference templates, not legal advice."
                }
              }
            }
          },
          "400": {
            "description": "Query missing or shorter than 2 characters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchError"
                },
                "example": {
                  "error": "Provide ?q= with at least 2 characters.",
                  "usage": "https://forms-legal.com/api/search-docs?q=non-disclosure+agreement&country=usa&limit=15",
                  "options": "lang=en returns English titles for every document; by default a document of a native-language jurisdiction is returned in its own language.",
                  "fields": ["title", "url", "country", "category", "subcategory", "jurisdiction", "summary", "language", "slug", "title_en"]
                }
              }
            }
          }
        }
      }
    },
    "/api/citation": {
      "get": {
        "operationId": "getCitation",
        "summary": "Generate a citation for a Forms Legal page",
        "description": "One-click citation generator for any forms-legal.com page (document detail pages, country/comparison hubs, dataset page, glossary terms, press kit). Returns a properly-formatted citation in the requested academic format. Plain-text formats (bibtex, ris, apa, chicago, mla) are returned as text; datacite and csl are returned as JSON.",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "description": "A full forms-legal.com page URL to cite.",
            "schema": {
              "type": "string",
              "format": "uri"
            },
            "example": "https://forms-legal.com/usa/business/contracts/non-disclosure-agreement"
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "description": "Citation format. Defaults to bibtex.",
            "schema": {
              "type": "string",
              "enum": ["bibtex", "ris", "datacite", "csl", "apa", "chicago", "mla"],
              "default": "bibtex"
            },
            "example": "bibtex"
          }
        ],
        "responses": {
          "200": {
            "description": "The formatted citation. Content type depends on the requested format.",
            "content": {
              "application/x-bibtex": {
                "schema": {
                  "type": "string"
                },
                "example": "@online{formslegal2026nondisclosureagreement,\n  author       = {{Forms Legal}},\n  title        = {{Non-Disclosure Agreement — United States}},\n  year         = {2026},\n  url          = {https://forms-legal.com/usa/business/contracts/non-disclosure-agreement},\n  urldate      = {2026-06-06},\n  note         = {Free legal-document template for United States.},\n  organization = {{Forms Legal}}\n}\n"
              },
              "application/x-research-info-systems": {
                "schema": {
                  "type": "string"
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                },
                "example": "Forms Legal. (2026). *Non-Disclosure Agreement — United States*. Forms Legal. Retrieved 2026-06-06, from https://forms-legal.com/usa/business/contracts/non-disclosure-agreement"
              },
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "DataCite (object) or CSL-JSON (array) metadata, depending on the requested format."
                }
              }
            }
          },
          "400": {
            "description": "Missing required url parameter.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CitationError"
                },
                "example": {
                  "error": "Missing required parameter: url",
                  "usage": "GET /api/citation?url=<full-page-url>&format=<bibtex|ris|datacite|csl|apa|chicago|mla>",
                  "defaultFormat": "bibtex"
                }
              }
            }
          },
          "404": {
            "description": "The URL was not recognized as a citable forms-legal.com page.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CitationError"
                },
                "example": {
                  "error": "URL not recognized as a forms-legal.com page that can be cited",
                  "url": "https://forms-legal.com/unknown",
                  "hint": "Try a doc detail URL like https://forms-legal.com/usa/business/contracts/non-disclosure-agreement"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SearchResult": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "description": "Document title in the language reported by `language`: the native language of the jurisdiction by default, or the language requested with ?lang=. English for English-speaking jurisdictions."
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Canonical absolute URL of the document page."
          },
          "country": {
            "type": "string",
            "description": "Country slug of the jurisdiction."
          },
          "category": {
            "type": "string",
            "description": "Top-level category (business, real-estate, personal, estate-planning, employment, financial, government)."
          },
          "subcategory": {
            "type": "string",
            "description": "Subcategory within the category."
          },
          "jurisdiction": {
            "type": "string",
            "description": "Primary governing statute for the template, when available.",
            "nullable": true
          },
          "summary": {
            "type": "string",
            "description": "Short description of the document, when available, in the same language as the other localized fields.",
            "nullable": true
          },
          "language": {
            "type": "string",
            "description": "Locale code of the language `title` is actually in (for example en, es, pt, fr, de, it). It can differ from the requested language when the document has no title in it and the English one was used."
          },
          "slug": {
            "type": "string",
            "description": "The last path segment of `url` (the document slug used in the canonical URL; native-language for native-language jurisdictions)."
          },
          "title_en": {
            "type": "string",
            "description": "English title of the document. Present only when `title` is not in English.",
            "nullable": true
          }
        },
        "required": ["title", "url", "country", "category", "subcategory"]
      },
      "SearchResponse": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "description": "The query that was executed."
          },
          "country": {
            "type": "string",
            "description": "The country filter applied, or \"all\" if none."
          },
          "lang": {
            "type": "string",
            "description": "The language override applied: a locale code when ?lang= was supported, or \"native\" when each document is shown in the native language of its jurisdiction."
          },
          "count": {
            "type": "integer",
            "description": "Number of results returned."
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SearchResult"
            }
          },
          "note": {
            "type": "string",
            "description": "Standing disclaimer."
          }
        },
        "required": ["query", "country", "count", "results"]
      },
      "SearchError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "usage": {
            "type": "string"
          },
          "options": {
            "type": "string",
            "description": "Short note on the optional lang parameter."
          },
          "fields": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": ["error"]
      },
      "CitationError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "usage": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "hint": {
            "type": "string"
          },
          "defaultFormat": {
            "type": "string"
          }
        },
        "required": ["error"]
      }
    }
  }
}