{
 "openapi": "3.1.0",
 "info": {
  "title": "USVI Public Records — static API v1",
  "version": "20260909-49102cb6",
  "description": "The public record of the U.S. Virgin Islands, as data. Static files on Cloudflare R2: there is no server, no key, no quota and no rate limit, and egress is free. Prefer the bulk catalogue over crawling.\n\nSearch is deliberately absent — static files cannot filter. Use the MCP server at https://mcp.usvipublicrecords.com/mcp, the site's own search, or the bulk databases.",
  "contact": {
   "email": "tips@viupdate.com"
  },
  "license": {
   "name": "See terms",
   "url": "https://usvipublicrecords.com/how"
  }
 },
 "servers": [
  {
   "url": "https://files.usvipublicrecords.com/api/v1"
  }
 ],
 "paths": {
  "/index.json": {
   "get": {
    "summary": "Discovery — start here",
    "operationId": "getIndex",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Index"
        }
       }
      }
     },
     "404": {
      "description": "This endpoint is missing, which means this API is broken. It does not indicate a withdrawn document — see x-document-record for that."
     }
    }
   }
  },
  "/stats.json": {
   "get": {
    "summary": "Corpus statistics",
    "operationId": "getStats",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Stats"
        }
       }
      }
     },
     "404": {
      "description": "This endpoint is missing, which means this API is broken. It does not indicate a withdrawn document — see x-document-record for that."
     }
    }
   }
  },
  "/collections.json": {
   "get": {
    "summary": "Collections and counts",
    "operationId": "getCollections",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Collections"
        }
       }
      }
     },
     "404": {
      "description": "This endpoint is missing, which means this API is broken. It does not indicate a withdrawn document — see x-document-record for that."
     }
    }
   }
  },
  "/entities.json": {
   "get": {
    "summary": "Entities and counts",
    "operationId": "getEntities",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Entities"
        }
       }
      }
     },
     "404": {
      "description": "This endpoint is missing, which means this API is broken. It does not indicate a withdrawn document — see x-document-record for that."
     }
    }
   }
  },
  "/catalogue.jsonl.gz": {
   "get": {
    "summary": "Every published document, one JSON object per line",
    "operationId": "getCatalogue",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/gzip": {
        "schema": {
         "type": "string",
         "format": "binary"
        },
        "x-line-format": "one CatalogueEntry JSON object per line, gzipped"
       }
      }
     },
     "404": {
      "description": "This endpoint is missing, which means this API is broken. It does not indicate a withdrawn document — see x-document-record for that."
     }
    }
   }
  },
  "/pages/{page}.json": {
   "get": {
    "summary": "The catalogue in 100-document pages",
    "operationId": "getPage",
    "parameters": [
     {
      "name": "page",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer",
       "minimum": 1
      },
      "description": "1..890"
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Page"
        }
       }
      }
     },
     "404": {
      "description": "This endpoint is missing, which means this API is broken. It does not indicate a withdrawn document — see x-document-record for that."
     }
    }
   }
  },
  "/datapackage.json": {
   "get": {
    "summary": "Frictionless Data descriptor for the bulk files",
    "operationId": "getDataPackage",
    "responses": {
     "200": {
      "description": "OK"
     },
     "404": {
      "description": "This endpoint is missing, which means this API is broken. It does not indicate a withdrawn document — see x-document-record for that."
     }
    }
   }
  },
  "/openapi.json": {
   "get": {
    "summary": "This document",
    "operationId": "getOpenApi",
    "responses": {
     "200": {
      "description": "OK"
     },
     "404": {
      "description": "This endpoint is missing, which means this API is broken. It does not indicate a withdrawn document — see x-document-record for that."
     }
    }
   }
  }
 },
 "x-document-record": {
  "description": "The per-document record is served from the file host, not under /api/v1 — it is the same object the website itself reads, deliberately not forked. It is the ONE place where a 404 means a withdrawal rather than a broken API.",
  "url": "https://files.usvipublicrecords.com/meta/{lf_id}.json",
  "parameters": [
   {
    "name": "lf_id",
    "required": true,
    "schema": {
     "type": "string",
     "pattern": "^LF-[0-9a-f]{12}$"
    },
    "description": "Archive id, e.g. LF-000322457c56 — substituted into the `url` template above, which is served by the file host, not by this API."
   }
  ],
  "responses": {
   "200": {
    "description": "OK",
    "content": {
     "application/json": {
      "schema": {
       "$ref": "#/components/schemas/DocumentRecord"
      }
     }
    }
   },
   "404": {
    "description": "No such document, or it has been withdrawn. 404 is authoritative and identical across the website, this API and the MCP server."
   }
  }
 },
 "components": {
  "schemas": {
   "CatalogueEntry": {
    "type": "object",
    "description": "One line of catalogue.jsonl.gz, and one element of a page's results array. Keys are OMITTED when empty rather than sent as null.",
    "required": [
     "lf_id",
     "sha256",
     "title",
     "collection",
     "file",
     "meta",
     "page"
    ],
    "properties": {
     "lf_id": {
      "type": "string",
      "pattern": "^LF-[0-9a-f]{12}$",
      "description": "Archive id: the first 12 hex of the file's SHA-256, so it is content-addressed and stable to cite."
     },
     "sha256": {
      "type": "string",
      "description": "Of the original file, for integrity checking."
     },
     "title": {
      "type": "string"
     },
     "collection": {
      "type": "string"
     },
     "sub_collection": {
      "type": "string"
     },
     "entity": {
      "type": "string",
      "description": "The body this record is ABOUT, resolved to one canonical spelling. Present on a MINORITY of documents; filtering on it also excludes every document whose entity is simply blank."
     },
     "issuer": {
      "type": "string",
      "description": "Who published it, which is not always who it is about. A court opinion against an agency is issued by the court and about the agency."
     },
     "date": {
      "type": "string",
      "description": "The date the archive recorded. PROVENANCE VARIES: usually the date on the document, sometimes the date the source posted the file. Read the date from the document itself when it matters to your answer."
     },
     "doc_type": {
      "type": "string"
     },
     "contentType": {
      "type": "string"
     },
     "primaryIsland": {
      "type": "string"
     },
     "identifiers": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "topics": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "pages": {
      "type": "integer"
     },
     "bytes": {
      "type": "integer"
     },
     "text_status": {
      "type": "string",
      "enum": [
       "native-text",
       "ocr-text",
       "text-on-disk",
       "image-only",
       "none"
      ],
      "description": "ocr-text has NOT been proofread and can carry recognition errors; the archival file is the record, not the extraction."
     },
     "source_url": {
      "type": "string",
      "format": "uri",
      "description": "Where this document came from. Every record has one."
     },
     "first_seen": {
      "type": "string"
     },
     "last_modified": {
      "type": "string"
     },
     "source_status": {
      "type": "string",
      "description": "Origin liveness and drift at the last recheck. ABSENT UNTIL MEASURED — its absence is not a finding."
     },
     "source_last_checked": {
      "type": "string"
     },
     "last_verified": {
      "type": "string",
      "description": "Local fixity check."
     },
     "web_archive_captures": {
      "type": "integer",
      "description": "Wayback captures of source_url. 0 means measured-and-none, which is different from absent."
     },
     "frame_id": {
      "type": "string",
      "description": "Membership in an enumerable series, e.g. acts-of-legislature."
     },
     "frame_seq": {
      "type": "integer"
     },
     "file": {
      "type": "string",
      "description": "Key on this host, e.g. docs/LF-….pdf"
     },
     "text": {
      "type": "string",
      "description": "Key, present when text exists."
     },
     "meta": {
      "type": "string",
      "description": "Key of the full record."
     },
     "preview": {
      "type": "string",
      "description": "A playable rendition where the original cannot play in a browser."
     },
     "page": {
      "type": "string",
      "format": "uri",
      "description": "The human page for this document."
     }
    }
   },
   "DocumentRecord": {
    "type": "object",
    "description": "meta/{lf_id}.json — the full per-document record, and the same object the website itself reads. A superset of a CatalogueEntry; it is deliberately NOT forked into a second copy under /api/v1 that could drift from it.",
    "allOf": [
     {
      "$ref": "#/components/schemas/CatalogueEntry"
     }
    ],
    "properties": {
     "tagIds": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "The triple-tag structure the site renders."
     },
     "entity_tags": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Bodies MENTIONED in the text above a threshold. A mention, not a subject — measured agreement with `entity` is about 51%, so do not treat it as one."
     },
     "keywords": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "has_thumb": {
      "type": "boolean"
     },
     "words": {
      "type": "integer"
     },
     "text_key": {
      "type": "string"
     },
     "file_key": {
      "type": "string"
     }
    }
   },
   "Index": {
    "type": "object",
    "required": [
     "build_id",
     "documents",
     "endpoints"
    ],
    "properties": {
     "build_id": {
      "type": "string",
      "description": "The ONE version string every artifact reports — this file, openapi.json, datapackage.json and the MCP server's archive_stats. One request tells you whether your copy is current."
     },
     "generated_at": {
      "type": "string",
      "format": "date-time"
     },
     "documents": {
      "type": "integer",
      "description": "The WHOLE archive, newspapers included."
     },
     "endpoints": {
      "type": "object",
      "additionalProperties": {
       "type": "string"
      }
     },
     "conventions": {
      "type": "object"
     },
     "terms": {
      "type": "string",
      "format": "uri"
     },
     "contact": {
      "type": "string"
     },
     "notes": {
      "type": "array",
      "items": {
       "type": "string"
      }
     }
    }
   },
   "Stats": {
    "type": "object",
    "properties": {
     "build_id": {
      "type": "string"
     },
     "generated": {
      "type": "string"
     },
     "totals": {
      "type": "object"
     },
     "collections": {
      "type": "array",
      "items": {
       "type": "object"
      }
     }
    }
   },
   "Collections": {
    "type": "object",
    "properties": {
     "build_id": {
      "type": "string"
     },
     "collections": {
      "type": "array",
      "items": {
       "type": "object",
       "required": [
        "name",
        "documents"
       ],
       "properties": {
        "name": {
         "type": "string"
        },
        "documents": {
         "type": "integer"
        },
        "date_min": {
         "type": [
          "string",
          "null"
         ]
        },
        "date_max": {
         "type": [
          "string",
          "null"
         ]
        }
       }
      }
     }
    }
   },
   "Entities": {
    "type": "object",
    "properties": {
     "build_id": {
      "type": "string"
     },
     "note": {
      "type": "string"
     },
     "entities": {
      "type": "array",
      "items": {
       "type": "object",
       "required": [
        "name",
        "documents"
       ],
       "properties": {
        "name": {
         "type": "string"
        },
        "documents": {
         "type": "integer"
        },
        "collections": {
         "type": "array",
         "items": {
          "type": "string"
         }
        },
        "date_min": {
         "type": [
          "string",
          "null"
         ]
        },
        "date_max": {
         "type": [
          "string",
          "null"
         ]
        }
       }
      }
     }
    }
   },
   "Page": {
    "type": "object",
    "required": [
     "page",
     "pages",
     "page_size",
     "results"
    ],
    "properties": {
     "build_id": {
      "type": "string"
     },
     "page": {
      "type": "integer"
     },
     "pages": {
      "type": "integer"
     },
     "page_size": {
      "type": "integer"
     },
     "documents": {
      "type": "integer"
     },
     "next": {
      "type": [
       "string",
       "null"
      ],
      "format": "uri"
     },
     "prev": {
      "type": [
       "string",
       "null"
      ],
      "format": "uri"
     },
     "results": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/CatalogueEntry"
      }
     }
    }
   }
  }
 },
 "x-conventions": {
  "file": "https://files.usvipublicrecords.com/docs/{lf_id}{ext}",
  "text": "https://files.usvipublicrecords.com/text/{lf_id}.txt",
  "thumb": "https://files.usvipublicrecords.com/thumbs/{sm|md}/{lf_id}.jpg",
  "page": "https://usvipublicrecords.com/doc/{lf_id}",
  "mcp": "https://mcp.usvipublicrecords.com/mcp"
 }
}