{
  "openapi": "3.1.0",
  "info": {
    "title": "GetLawED — verified South African law API",
    "version": "1.0.0",
    "summary": "Search official South African legal texts, read a section and check citations against official copies.",
    "description": "REST access to the GetLawED library (18,656 judgments, 1,901 Acts, 1,202 regulations/rules, 235 by-laws and schemes, 43,881 gazette notices, 550 Bills; 171,521 sections). The same tools are available over MCP at https://getlawed.co.za/api/mcp/law. Every call counts against your plan (free: 25 searches + 50 citation checks a day without a key). Results are not legal advice; legislation is shown as published and later amendments may not be applied. Terms: https://getlawed.co.za/law/terms.html (version 2026-10-13).",
    "termsOfService": "https://getlawed.co.za/law/terms.html",
    "contact": {
      "name": "GetLawED support",
      "email": "support@getkonnekted.com",
      "url": "https://getlawed.co.za/law/developers/"
    }
  },
  "servers": [
    {
      "url": "https://getlawed.co.za/api/law/v1"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    },
    {}
  ],
  "paths": {
    "/search": {
      "get": {
        "operationId": "searchLibrary",
        "summary": "Search the library",
        "description": "Full-text search over official South African legal texts. Acts, regulations and by-laws are ranked at section level; judgments as whole documents. Absence from the results does not mean an authority does not exist. Counts as one search.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "What to look for, in plain language (at least two meaningful words, max 500 characters).",
            "schema": {
              "type": "string",
              "maxLength": 500
            },
            "example": "unfair dismissal reinstatement"
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "Kind of document: judgment, act, regulation (regulations, rules and codes), bylaw (municipal by-laws and land use schemes), notice (Government Gazette notices), bill, or any (default).",
            "schema": {
              "type": "string",
              "enum": [
                "judgment",
                "act",
                "regulation",
                "bylaw",
                "notice",
                "bill",
                "any"
              ],
              "default": "any"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum results, 1–10.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10,
              "default": 5
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching documents",
            "headers": {
              "X-GetLawED-Plan": {
                "$ref": "#/components/headers/Plan"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad input (code bad_request)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid API key (code invalid_key)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/QuotaExceeded"
          },
          "500": {
            "description": "Server error (code server_error)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/section": {
      "get": {
        "operationId": "getSection",
        "summary": "Read one section or judgment",
        "description": "Full text of one section of a document returned by /search (or, for judgments, the judgment text or the part matching `section`), capped at 12,000 characters. If `section` matches nothing, the list of sections is returned instead. Counts as one search.",
        "parameters": [
          {
            "name": "doc_id",
            "in": "query",
            "required": true,
            "description": "doc_id from a search result.",
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "example": 50657
          },
          {
            "name": "section",
            "in": "query",
            "required": false,
            "description": "Section reference as returned (e.g. \"Section 193: Remedies for unfair dismissal and unfair labour practice\") or a number like \"193\". For judgments: a paragraph number or phrase.",
            "schema": {
              "type": "string",
              "maxLength": 200
            },
            "example": "193"
          }
        ],
        "responses": {
          "200": {
            "description": "The section text, or the list of sections",
            "headers": {
              "X-GetLawED-Plan": {
                "$ref": "#/components/headers/Plan"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/SectionResponse"
                    },
                    {
                      "$ref": "#/components/schemas/SectionListResponse"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad input (code bad_request)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid API key (code invalid_key)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such document in the library (code not_found)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/QuotaExceeded"
          },
          "500": {
            "description": "Server error (code server_error)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/verify": {
      "post": {
        "operationId": "verifyCitations",
        "summary": "Check case citations and Acts",
        "description": "Finds South African case citations (neutral and law-report) and Acts in the text and checks each against GetLawED's official copies and verified records. Counts as one citation check.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "text"
                ],
                "properties": {
                  "text": {
                    "type": "string",
                    "maxLength": 20000,
                    "description": "Text containing the citations."
                  }
                }
              },
              "example": {
                "text": "See S v Makwanyane and Another 1995 (3) SA 391 (CC) and the Labour Relations Act 66 of 1995."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "One entry per citation found",
            "headers": {
              "X-GetLawED-Plan": {
                "$ref": "#/components/headers/Plan"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerifyResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad input (code bad_request)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid API key (code invalid_key)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/QuotaExceeded"
          },
          "500": {
            "description": "Server error (code server_error)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "GetLawED API key (glw_…) from https://getlawed.co.za/law/access.html. Optional: without it, free-tier limits apply per IP address. An invalid key is refused with 401 (it does not fall back to the free tier)."
      }
    },
    "headers": {
      "Plan": {
        "description": "The plan the call was counted against (free, professional, firm, developer, scale).",
        "schema": {
          "type": "string"
        }
      },
      "RetryAfter": {
        "description": "Seconds until the allowance resets (South African midnight for daily limits, the 1st of the month for monthly plans).",
        "schema": {
          "type": "integer"
        }
      }
    },
    "responses": {
      "QuotaExceeded": {
        "description": "Plan allowance used up (code quota_exceeded)",
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/QuotaError"
            }
          }
        }
      }
    },
    "schemas": {
      "Result": {
        "type": "object",
        "required": [
          "doc_id",
          "type",
          "title",
          "url"
        ],
        "properties": {
          "doc_id": {
            "type": "integer",
            "description": "GetLawED library reference; pass it to /section."
          },
          "type": {
            "type": "string",
            "enum": [
              "judgment",
              "act",
              "regulation",
              "bylaw",
              "notice",
              "bill"
            ],
            "description": "Kind of document."
          },
          "title": {
            "type": "string"
          },
          "section": {
            "type": "string",
            "description": "Best-matching section (Acts, regulations, by-laws)."
          },
          "citation": {
            "type": "string",
            "description": "Neutral citation of a judgment, e.g. [2019] ZACC 1."
          },
          "case_number": {
            "type": "string"
          },
          "court": {
            "type": "string"
          },
          "date": {
            "type": "string",
            "format": "date",
            "description": "Date of judgment."
          },
          "act": {
            "type": "string",
            "description": "e.g. \"Act 66 of 1995\"."
          },
          "gazette": {
            "type": "string",
            "description": "Government Gazette reference."
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Official source (court, gov.za, Government Printer, provincial gazette, municipality or regulator)."
          },
          "excerpt": {
            "type": "string",
            "description": "Short matching passage (≤ 400 characters)."
          }
        }
      },
      "SearchResponse": {
        "type": "object",
        "required": [
          "results",
          "source_note"
        ],
        "properties": {
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Result"
            }
          },
          "source_note": {
            "type": "string",
            "description": "Attribution and reliance note. Show \"Verified by GetLawED\" with a link to getlawed.co.za (or the cited page) wherever results are displayed."
          }
        }
      },
      "SectionResponse": {
        "type": "object",
        "required": [
          "doc_id",
          "title",
          "url",
          "text",
          "source_note"
        ],
        "properties": {
          "doc_id": {
            "type": "integer"
          },
          "title": {
            "type": "string"
          },
          "section": {
            "type": [
              "string",
              "null"
            ],
            "description": "Section returned (null for judgments)."
          },
          "gazette": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "text": {
            "type": "string",
            "description": "Up to 12,000 characters."
          },
          "source_note": {
            "type": "string",
            "description": "Attribution and reliance note. Show \"Verified by GetLawED\" with a link to getlawed.co.za (or the cited page) wherever results are displayed."
          }
        }
      },
      "SectionListResponse": {
        "type": "object",
        "required": [
          "doc_id",
          "title",
          "sections",
          "source_note"
        ],
        "description": "Returned when `section` matched nothing (or was left out for a sectioned document).",
        "properties": {
          "doc_id": {
            "type": "integer"
          },
          "title": {
            "type": "string"
          },
          "sections": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "source_note": {
            "type": "string"
          }
        }
      },
      "CaseCheck": {
        "type": "object",
        "required": [
          "cited",
          "status"
        ],
        "properties": {
          "cited": {
            "type": "string",
            "description": "The citation as found in the text."
          },
          "status": {
            "type": "string",
            "enum": [
              "found",
              "mismatch",
              "name_only",
              "not_found",
              "unchecked"
            ],
            "description": "found: The citation was confirmed and the parties match: for a neutral citation (e.g. [1995] ZACC 3), our official copy of that judgment has these parties; for a law-report citation (e.g. 1995 (3) SA 391 (CC)), judgments in our library cite it next to its neutral citation, and our official copy of that judgment has these parties. | mismatch: The citation exists but belongs to a different case — the parties in our official copy do not match the name given. Treat as a likely wrong or invented citation and check it. | name_only: A judgment with these parties is in our library, but the citation itself could not be confirmed (e.g. a law-report citation we have not mapped). Check the citation against the report. | not_found: Nothing matching was found in the databases searched. Older reported cases are often not online — \"not found\" means \"check the law reports\", not \"fake\". | unchecked: The citation could not be checked against the sources available to this check (in the public API: GetLawED's own library and verified records only). It is neither confirmed nor accused."
          },
          "matched_title": {
            "type": "string",
            "description": "Title of the judgment we matched."
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Official source of the matched judgment."
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Where the confirmation came from."
          }
        }
      },
      "ActCheck": {
        "type": "object",
        "required": [
          "cited",
          "status"
        ],
        "properties": {
          "cited": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "found",
              "repealed",
              "number_mismatch",
              "not_found",
              "unchecked"
            ],
            "description": "found: An Act with this number and year is held (official copy) or recorded, and the name agrees. Unless the source says otherwise, repeal status has not been checked. | repealed: Found, but our verified records mark the Act as repealed. Check what replaced it. | number_mismatch: An Act with this name and year exists, but with a different number. Check the Act number. | not_found: No Act with this name, number and year was found in the databases searched. | unchecked: The Act could not be checked against the sources available to this check."
          },
          "matched_title": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "VerifyResponse": {
        "type": "object",
        "required": [
          "cases",
          "acts",
          "source_note"
        ],
        "properties": {
          "cases": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CaseCheck"
            }
          },
          "acts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ActCheck"
            }
          },
          "source_note": {
            "type": "string",
            "description": "Attribution and reliance note. Show \"Verified by GetLawED\" with a link to getlawed.co.za (or the cited page) wherever results are displayed."
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error",
          "code"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Plain-language message."
          },
          "code": {
            "type": "string",
            "enum": [
              "bad_request",
              "invalid_key",
              "not_found",
              "quota_exceeded",
              "server_error",
              "RATE_LIMITED"
            ]
          }
        }
      },
      "QuotaError": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Error"
          },
          {
            "type": "object",
            "properties": {
              "plan": {
                "type": "string"
              },
              "upgrade": {
                "type": "string",
                "format": "uri"
              },
              "retry_after_seconds": {
                "type": "integer"
              }
            }
          }
        ]
      }
    }
  }
}