GET /api/admin/shares

List all retained share statuses (requires administrator authentication).

Headers:

Authorization: Bearer [access-token]

Query Parameters:

• page - One-based page number, default 1.
• perPage - Rows per page from 1 to 100, default 10.
• sort - JSON array ["field","ASC|DESC"]. Fields: createdAt, expiresAt, deletedAt, sharer, anchorKind.
• filter - JSON object. Fields: q, status, anchorKind, sharerUserId, createdFrom, createdTo, expiresFrom, expiresTo. Date upper bounds are exclusive.

Example Request:

GET /api/admin/shares?page=1&perPage=10&sort=["createdAt","DESC"]&filter={"status":"active"}

Response (200 OK):

{
    "data": [{
        "shareId": 123,
        "sharer": { "userId": 42, "email": "reader@example.com", "username": "reader" },
        "anchor": {
            "anchorKind": "bible",
            "readerContext": { "bibleVersion": "esv", "commentaryTranslation": "english" },
            "bookIndex": 43,
            "chapterNum": 3,
            "startVerse": 16,
            "endVerse": 17,
            "startParaId": null,
            "endParaId": null,
            "contextBibleRef": null,
            "contextSource": null
        },
        "comment": "Read this passage",
        "status": "active",
        "singleUse": false,
        "createdAt": "2026-09-12T12:00:00.000Z",
        "expiresAt": "2026-09-19T12:00:00.000Z",
        "consumedAt": null,
        "deletedAt": null,
        "deletedByUserId": null,
        "deletionReason": null
    }],
    "total": 1
}

Response Headers:

Content-Range: shares 0-0/1
Accept-Range: shares
Access-Control-Expose-Headers: Content-Range
X-Total-Count: 1

GET /api/shares/:shareCode

Resolve an unexpired, unconsumed, unrevoked share without authentication or subscription checks.

URL Parameters:

• shareCode - The 43-character opaque code from a public share URL.

Response (200 OK, Bible):

{
    "contentType": "bible",
    "anchor": {
        "contentType": "bible",
        "bibleVersion": "esv",
        "bookIndex": 43,
        "chapterNum": 3,
        "startVerse": 16,
        "endVerse": 17
    },
    "selector": {
        "exact": "For God so loved the world",
        "prefix": "context before ",
        "suffix": " context after",
        "startOffset": 10,
        "endOffset": 36
    },
    "comment": "Read this passage",
    "expiresAt": "2026-09-19T12:00:00.000Z"
}

Response (404 Not Found):

{
    "status": "unavailable",
    "message": "This shared passage can no longer be opened."
}

Notes:

• Malformed, missing, expired, consumed, and revoked codes return the same status and body.
• The request is rate-limited to 60 attempts per IP per 15 minutes.

POST /api/admin/shares/lookup

Look up a reported raw code exactly (requires administrator authentication and CSRF).

Headers:

Authorization: Bearer [access-token]
x-csrf-token: [csrf-token]

Request Body:

{ "shareCode": "[reported-43-character-code]" }

Response (200 OK):

{
    "shareId": 123,
    "sharer": { "userId": 42, "email": "reader@example.com", "username": "reader" },
    "anchor": {
        "anchorKind": "commentary",
        "readerContext": { "bibleVersion": "esv", "commentaryTranslation": "english" },
        "bookIndex": 44,
        "chapterNum": 23,
        "startVerse": null,
        "endVerse": null,
        "startParaId": "Acts_commentary_023_00075",
        "endParaId": "Acts_commentary_023_00077",
        "contextBibleRef": { "bookIndex": 44, "chapterNum": 23, "verse": 2, "endVerse": 5 },
        "contextSource": "subsection"
    },
    "comment": "Read this commentary",
    "status": "active",
    "singleUse": false,
    "createdAt": "2026-09-12T12:00:00.000Z",
    "expiresAt": "2026-09-19T12:00:00.000Z",
    "consumedAt": null,
    "deletedAt": null,
    "deletedByUserId": null,
    "deletionReason": null
}

Error Response (404 Not Found):

{ "message": "Share not found" }

Notes:

• Submit the code only in this POST body, never in a query parameter.
• The Server hashes it immediately and never echoes it.
• The request is rate-limited to 30 attempts per administrator per 15 minutes.

POST /api/shares

Create a transitional public share (requires authentication and CSRF; public feature flag must be enabled).

Headers:

Authorization: Bearer [access-token]
x-csrf-token: [csrf-token]

Request Body (Bible):

{
    "anchor": {
        "contentType": "bible",
        "bibleVersion": "esv",
        "bookIndex": 43,
        "chapterNum": 3,
        "startVerse": 16,
        "endVerse": 17
    },
    "selector": { "exact": "For God so loved the world", "startOffset": 10, "endOffset": 36 },
    "comment": "Read this passage"
}

Request Body (Commentary):

{
    "anchor": {
        "contentType": "commentary",
        "commentaryTranslation": "english",
        "bookIndex": 44,
        "chapterNum": 23,
        "startParaId": "Acts_commentary_023_00075",
        "endParaId": "Acts_commentary_023_00077",
        "contextBibleRef": { "bookIndex": 44, "chapterNum": 23, "verse": 2, "endVerse": 5 },
        "contextSource": "subsection"
    },
    "selector": { "exact": "The high priest interpreted Paul's claim" }
}

Response (201 Created):

{
    "shareId": "[43-character-opaque-code]",
    "url": "https://digital.lmw.org/share/[43-character-opaque-code]",
    "expiresAt": "2026-09-19T12:00:00.000Z"
}

Validation:

• Bible versions are esv and kjv; commentary translation is english.
• Book indexes are 1 through 66, numeric ranges must be ordered, selector exact must be non-empty, and comments have a 300-character maximum.
• Unknown fields, caller-supplied TTL, sharer, singleUse, and any textSnapshot are rejected.
• Commentary contextSource requires contextBibleRef. Observable cross-chapter context is rejected; omitted ambiguity cannot be verified without a Server content manifest.
• Creation is rate-limited to 20 requests per authenticated user per hour.

DELETE /api/admin/shares/:shareId

Idempotently revoke a share by its numeric Admin ID (requires administrator authentication and CSRF).

Headers:

Authorization: Bearer [access-token]
x-csrf-token: [csrf-token]

URL Parameters:

• shareId - Positive numeric share record ID, not the public raw code.

Request Body:

{ "reason": "Reported abusive content" }

Response (200 OK):

{
    "status": "deleted",
    "shareId": 123,
    "deletedAt": "2026-09-13T09:00:00.000Z",
    "deletedByUserId": 7,
    "deletionReason": "Reported abusive content"
}

Notes: Repeated requests return the original deletion timestamp, administrator, and 1-300-character reason. The request is rate-limited to 30 attempts per administrator per 15 minutes.