Lexicon Reference

Wisp.place uses three custom AT Protocol lexicons to store site data in your PDS.

place.wisp.fs — the main site manifest. Stores the full directory tree with references to file blobs.

place.wisp.subfs — subtree records for splitting large sites across multiple records. Entries from subfs records are merged into the parent directory.

place.wisp.settings — per-site configuration: routing behavior, index files, directory listing, and custom HTTP headers.

place.wisp.domain — metadata record for claiming a wisp.place subdomain.

place.wisp.v2.wh — webhook record for receiving HTTP callbacks when AT Protocol records change.

place.wisp.v2.secret.{create,list,delete,rotate} — server-managed signing secrets for webhooks. Tokens are returned once at creation and stored as encrypted server-side envelopes; they cannot be retrieved later. Operators must configure and rotate the encryption key safely. See the webhooks doc and deployment guide.

place.wisp.auth* — OAuth permission sets that bundle the granular scopes clients request during login.

Storage Model

Sites are stored as place.wisp.fs records in your AT Protocol repository:

at://did:plc:abc123/place.wisp.fs/my-site

Files are gzipped for compression and uploaded as application/octet-stream blobs. They may also be base64-encoded to bypass content sniffing on legacy reference PDS. The original MIME type is preserved in the manifest.

Sites with 250+ files are automatically split: large directories are extracted into place.wisp.subfs records, referenced by AT-URI from the main manifest, and merged back together by the hosting service at serve time. This keeps the main manifest under the 150 KB PDS record size limit.

Example Record

{
  "$type": "place.wisp.fs",
  "site": "my-site",
  "root": {
    "type": "directory",
    "entries": [
      {
        "name": "index.html",
        "node": {
          "type": "file",
          "blob": {
            "$type": "blob",
            "ref": { "$link": "bafyreiabc123..." },
            "mimeType": "application/octet-stream",
            "size": 12345
          },
          "encoding": "gzip",
          "mimeType": "text/html",
          "base64": true
        }
      }
    ]
  },
  "fileCount": 42,
  "createdAt": "2024-01-15T10:30:00Z"
}