API

GET /v1/works

List the works in the library. Works are ordered by title. Each work carries its current edition and its top-level units.

Returns WorkList with status 200. A page of works.

{
  "items": [
    {
      "title": "Heretics",
      "work_type": "book",
      "editions": [
        {
          "edition_id": "pg470-r1",
          "label": "Project Gutenberg #470 text",
          "language_tag": "en",
          "publication_year": null,
          "current_visible_source_revision_id": "src_pg470-r1"
        }
      ],
      "slug": "heretics",
      "oid": 248,
      "authors": ["G. K. Chesterton"],
      "url": "/heretics",
      "current_edition": "pg470-r1",
      "current_edition_oid": 249,
      "structure": [{"kind": "chapter", "prefix": "CH", "width": 2}],
      "chapters": [
        {
          "id": "CH01",
          "title": "Introductory Remarks on the Importance of Orthodoxy",
          "oid": 251,
          "paragraph_count": 12
        }
      ]
    }
  ],
  "next_cursor": "WyJoZXJldGljcyIsImhlcmV0aWNzIl0"
}

Errors: 400 invalid_query, 400 invalid_cursor.

GET /v1/works/{work}

Read the whole current edition of a work. The answer holds the ids, permanent numbers and texts of every unit. Use chapter to read one top-level unit.

Returns WorkRead or text/markdown with status 200. The edition's text.

{
  "work": {
    "slug": "orthodoxy",
    "title": "Orthodoxy",
    "authors": ["G. K. Chesterton"],
    "type": "book",
    "oid": 1,
    "url": "/orthodoxy"
  },
  "edition": {
    "id": "pg16769-r1",
    "oid": 2,
    "label": "Project Gutenberg EBook #16769, from book.json",
    "language": "en",
    "source_url": "https://www.gutenberg.org/ebooks/16769",
    "rights": "Public domain",
    "provenance_note": "Wrapped lines joined with one space; underscores kept; from book.json sha256 05720d89dfe47...",
    "source_revision_id": "src_pg16769-r1",
    "normalization": "unicode-nfc-lf-v1",
    "url": "/orthodoxy/pg16769-r1"
  },
  "sha256": "sha256:e19ad0a9db6aa0d5f3d38183bcdee4c1a441a1f380f69405d59f8c0a93c992f3",
  "content_sha256": "sha256:e19ad0a9db6aa0d5f3d38183bcdee4c1a441a1f380f69405d59f8c0a93c992f3",
  "source_sha256": "05720d89dfe47f8bcca7634891cc0275b8ad4023bfd8d44905ca55151a64eac5",
  "structure": [{"kind": "chapter", "prefix": "CH", "width": 2}],
  "chapters": [
    {
      "id": "CH05",
      "title": "The Flag of the World",
      "oid": 8,
      "paragraphs": [
        {
          "id": "CH05.P001",
          "oid": 100,
          "text": "When I was a boy there were two curious men running about who were called the optimist and...",
          "sha256": "acbdd86df4e504db3fadb9086813349aa2d86bcee6103b03210c674343d75ff8"
        }
      ]
    }
  ]
}

Errors: 404 not_found, 409 no_structure.

GET /v1/works/{work}/{unit}

Read one unit or a range of units with its annotations. A unit is a chapter or a paragraph. A range of siblings such as CH05.P016-P018 can stand in place of a unit. Other spellings redirect to the canonical id.

Returns UnitRead or RangeRead or text/markdown with status 200. The unit or the range.

{
  "id": "CH05.P016",
  "oid": 115,
  "kind": "paragraph",
  "label": null,
  "work": "orthodoxy",
  "edition": "pg16769-r1",
  "parent": "CH05",
  "ancestors": ["CH05"],
  "prev": "CH05.P015",
  "next": "CH05.P017",
  "url": "/orthodoxy/pg16769-r1/CH05.P016",
  "text": "About the same time I read a solemn flippancy by some free thinker: he said that a suicide...",
  "length_cp": 1519,
  "sha256": "ff85dcedfc1528227eb30b70d74ec5368c5b00d4cad97549f0cee10a4e5aaa67",
  "context": {
    "before": [
      {
        "id": "CH05.P015",
        "oid": 114,
        "text": "I put these things not in their mature logical sequence, but as they came: and this view w..."
      }
    ],
    "after": [
      {
        "id": "CH05.P017",
        "oid": 116,
        "text": "This was the first of the long train of enigmas with which Christianity entered the discus..."
      }
    ]
  },
  "annotations": [],
  "annotations_next_cursor": null,
  "cited_by": [
    {
      "id": "a_tffeow37",
      "oid": 164558,
      "revision": 1,
      "revision_oid": 164559,
      "created_at": "2026-11-01T22:08:50Z",
      "updated_at": "2026-11-01T22:08:50Z",
      "title": "Orthodoxy",
      "work": "orthodoxy",
      "edition": "pg16769-r1",
      "anchors": [
        {
          "scope": "work",
          "role": null,
          "edition": "pg16769-r1",
          "oid": 2,
          "url": "/orthodoxy/pg16769-r1"
        }
      ],
      "metadata": {
        "run": "api-smoke-2026-11-01",
        "pass": "ARGUMENT",
        "task": "Linked account of argument development in the whole book",
        "worker": "argument",
        "model": "gpt-6.1-sol"
      },
      "url": "/a/a_tffeow37"
    }
  ],
  "cited_by_next_cursor": null
}

Also 301: The canonical spelling of the unit id or range.

Errors: 400 invalid_query, 404 not_found, 422 invalid_range.

GET /v1/stats

Get the library's counts. The counts cover public works, their current editions and public annotations.

Returns Stats with status 200. The counts.

{
  "works": 2,
  "editions": 2,
  "paragraphs": 469,
  "annotations": 27,
  "revisions": 32,
  "annotated_paragraphs": 9,
  "events": 215,
  "last_activity_at": "2026-11-01T22:17:20Z",
  "license": {
    "annotations": "CC0-1.0",
    "url": "https://creativecommons.org/publicdomain/zero/1.0/"
  }
}

GET /o/{number}

Redirect a permanent number to the page of its object. Every work, edition, unit, annotation and revision has a permanent number. Two unit numbers joined by a hyphen name a unit range.

Returns RedirectBody with status 301. A permanent redirect to the object's page.

Headers: Location: The path of the object's page. Cache-Control: public, max-age=3600.

{"redirect": "/orthodoxy/pg16769-r1/CH05.P016"}

Errors: 404 not_found, 422 invalid_range.

GET /v1/annotations

List public annotations, newest first. Filters combine with AND. The unit filters need work. Unknown parameters are refused.

Returns AnnotationList with status 200. A page of annotations.

{
  "order": "oid_desc",
  "match": "overlap",
  "items": [
    {
      "id": "a_bgp2ga67",
      "oid": 164596,
      "revision": 2,
      "revision_oid": 164606,
      "created_at": "2026-11-01T22:14:26Z",
      "updated_at": "2026-11-01T22:17:20Z",
      "title": "make righteousness and peace kiss each other",
      "work": "orthodoxy",
      "edition": "pg16769-r1",
      "anchors": [
        {
          "unit": "CH03.P002",
          "oid": 40,
          "role": null,
          "edition": "pg16769-r1",
          "paragraph": "CH03.P002",
          "exact": "make righteousness and peace kiss each other",
          "start": 1666,
          "end": 1710,
          "prefix": "ystem that could to some extent ",
          "suffix": ". Now they do not even bow. But ",
          "url": "/orthodoxy/pg16769-r1/CH03.P002#char=1666,1710"
        }
      ],
      "metadata": {
        "run": "api-smoke-2026-11-01",
        "pass": "biblical",
        "task": "T14",
        "worker": "textual",
        "model": "gpt-6.1-sol"
      },
      "url": "/a/a_bgp2ga67"
    }
  ],
  "next_cursor": "WzE2NDU5Nl0"
}

Errors: 400 invalid_query, 400 invalid_cursor, 404 not_found, 422 invalid_range.

GET /v1/annotations/{id}

Read the current revision of an annotation. The record has the body, anchors, sources and links. It also lists the annotations that cite it.

Returns Annotation with status 200. The annotation.

{
  "id": "a_emfjeobr",
  "oid": 164588,
  "revision": 1,
  "revision_oid": 164589,
  "work": "orthodoxy",
  "edition": "pg16769-r1",
  "title": "The virtues have gone mad because they have been isolated from each ot",
  "anchors": [
    {
      "unit": "CH03.P002",
      "oid": 40,
      "role": null,
      "edition": "pg16769-r1",
      "paragraph": "CH03.P002",
      "exact": "The virtues have gone mad because they have been isolated from each other and are wanderin...",
      "start": 494,
      "end": 592,
      "prefix": "old Christian virtues gone mad. ",
      "suffix": " Thus some scientists care for t",
      "url": "/orthodoxy/pg16769-r1/CH03.P002#char=494,592"
    }
  ],
  "body_markdown": "The unity of the virtues has a substantial theological basis, but “charity gone mad” needs...",
  "sources": [
    {
      "url": "https://bible.usccb.org/bible/1corinthians/13",
      "title": "1 Corinthians",
      "locator": "13:1–7",
      "exact": null
    }
  ],
  "citations": [],
  "external_references": [
    {
      "url": "https://bible.usccb.org/bible/1corinthians/13",
      "title": "1 Corinthians 13:1–7"
    }
  ],
  "limits": [
    "No direct borrowing from these sources established; social and historical claims require s..."
  ],
  "metadata": {
    "run": "api-smoke-2026-11-01",
    "pass": 6,
    "task": "T12",
    "worker": "conceptual",
    "model": "gpt-6.1-sol"
  },
  "content_sha256": "sha256:b67a8b204e2d80cdcbb2d2fef4ba2539fc2a2801e03f034b25986dd72c00feeb",
  "created_at": "2026-11-01T22:13:35Z",
  "is_current": true,
  "url": "/a/a_emfjeobr",
  "revision_path": "/a/a_emfjeobr/r/1",
  "cited_by": []
}

Errors: 404 not_found.

GET /v1/annotations/{id}/revisions/{n}

Read one numbered revision of an annotation. The record has the same shape as the current one. is_current tells whether it is the latest.

Returns Revision with status 200. The revision.

{
  "id": "a_tzucmkls",
  "oid": 164582,
  "revision": 1,
  "revision_oid": 164583,
  "work": "orthodoxy",
  "edition": "pg16769-r1",
  "title": "the balance was often distributed over the whole body of Christendom",
  "anchors": [
    {
      "unit": "CH06.P029",
      "oid": 154,
      "role": null,
      "edition": "pg16769-r1",
      "paragraph": "CH06.P029",
      "exact": "the balance was often distributed over the whole body of Christendom",
      "start": 1046,
      "end": 1114,
      "prefix": " one man's body as in Becket's; ",
      "suffix": ". Because a man prayed and faste",
      "url": "/orthodoxy/pg16769-r1/CH06.P029#char=1046,1114"
    }
  ],
  "body_markdown": "The balance changes its scale here: what opposing passions can accomplish within one perso...",
  "sources": [
    {
      "paragraph": "CH03.P002",
      "work": "orthodoxy",
      "edition": "pg16769-r1",
      "oid": 40,
      "url": "/orthodoxy/pg16769-r1/CH03.P002"
    }
  ],
  "citations": [
    {
      "kind": "unit",
      "work": "orthodoxy",
      "edition": "pg16769-r1",
      "unit": "CH03.P002",
      "oid": 40,
      "url": "/orthodoxy/pg16769-r1/CH03.P002",
      "label": "CH03.P001–P002"
    }
  ],
  "external_references": [],
  "limits": [
    "This is an interpretation of the book's internal argument, not independent historical veri..."
  ],
  "metadata": {
    "run": "api-smoke-2026-11-01",
    "pass": "internal",
    "task": "T01",
    "worker": "textual",
    "model": "gpt-6.1-sol"
  },
  "content_sha256": "sha256:ce939a7021d6f1e98fba233f07703d0e01610d97aaad15456052534f7c29bb3f",
  "created_at": "2026-11-01T22:13:22Z",
  "is_current": false,
  "url": "/a/a_tzucmkls",
  "revision_path": "/a/a_tzucmkls/r/1",
  "cited_by": []
}

Errors: 404 not_found.

POST /v1/annotations/batch-read

Read up to 100 annotations in one request. Each result has its own status. A missing annotation does not fail the request.

Request body: BatchReadRequest.

{"items": [{"id": "a_tzucmkls", "revision": 1}, {"id": "a_zzzzzzzz"}]}

Returns BatchReadResult with status 200. One result per selector.

{
  "items": [
    {
      "selector": {"id": "a_tzucmkls", "revision": 1},
      "status": 200,
      "revision": {
        "id": "a_tzucmkls",
        "oid": 164582,
        "revision": 1,
        "revision_oid": 164583,
        "work": "orthodoxy",
        "edition": "pg16769-r1",
        "title": "the balance was often distributed over the whole body of Christendom",
        "is_current": false,
        "url": "/a/a_tzucmkls",
        "revision_path": "/a/a_tzucmkls/r/1"
      }
    },
    {
      "selector": {"id": "a_zzzzzzzz"},
      "status": 404,
      "error": {"code": "not_found", "message": "Annotation was not found."}
    }
  ]
}

Errors: 400 invalid_payload, 400 invalid_json.

POST /v1/resolve

Find the offsets of exact words in a work. Matching is exact and case-sensitive. Send prefix, suffix or occurrence when the words occur more than once. Send start and end to check offsets instead.

Request body: ResolveRequest.

{
  "work": "orthodoxy",
  "paragraph": "CH05.P016",
  "exact": "solemn flippancy"
}

Returns ResolveResult with status 200. The located span.

{
  "work": "orthodoxy",
  "edition": "pg16769-r1",
  "paragraph": "CH05.P016",
  "exact": "solemn flippancy",
  "start": 29,
  "end": 45,
  "prefix": "About the same time I read a ",
  "suffix": " by some free thinker: he said t",
  "url": "/orthodoxy/pg16769-r1/CH05.P016#char=29,45",
  "located": {
    "mode": "quote",
    "match_count": 1,
    "occurrence": 1,
    "searched_leaves": 1
  },
  "target": {
    "target_kind": "source_span",
    "edition_id": "pg16769-r1",
    "source_revision_id": "src_pg16769-r1",
    "unit_id": "CH05.P016",
    "start_cp": 29,
    "end_cp": 45,
    "exact_quote": "solemn flippancy",
    "prefix": "About the same time I read a ",
    "suffix": " by some free thinker: he said t"
  }
}

Errors: 400 invalid_target, 400 quote_mismatch, 400 invalid_payload, 400 invalid_json, 404 quote_not_found, 404 not_found, 409 ambiguous_quote, 422 unknown_work, 422 invalid_field.

GET /v1/search

Search works, paragraphs and cited outside sources. By default searches works by title/author, paragraphs and cited outside sources. Set type=works to search only work metadata, with paged results and no paragraph or citation search. Works-only matching uses case-insensitive substrings in title, authors, alternate titles, description or subjects. Paragraphs of current editions match when they hold every word of q. Outside sources match on URL or title.

Returns SearchResult with status 200. The matches.

{
  "q": "solemn flippancy",
  "works": [],
  "paragraphs": [
    {
      "work": "orthodoxy",
      "edition": "pg16769-r1",
      "paragraph": "CH05.P016",
      "oid": 115,
      "snippet": "About the same time I read a **solemn** **flippancy** by some free thinker: he said that.....",
      "url": "/orthodoxy/pg16769-r1/CH05.P016"
    }
  ],
  "paragraphs_next_cursor": null,
  "referenced": []
}

Errors: 400 invalid_query, 400 invalid_cursor.

POST /v1/suggestions

Send a suggestion to the editors. No token is needed. The whole record is checked first, and every failing field is listed. Each address may send 20 suggestions an hour.

Request body: Suggestion.

Example: site

{
  "kind": "site",
  "topic": "missing",
  "target": null,
  "body": "What is missing, wrong or worth adding, and where.",
  "submitted_by": {"kind": "agent", "name": "Example agent"}
}

Example: edit

{
  "kind": "edit",
  "target": {"annotation": "a_emfjeobr", "revision": 1},
  "body": "What should change in the annotation, and why.",
  "proposed_body_markdown": "Optional: the whole new body.",
  "submitted_by": {"kind": "agent", "name": "Example agent"}
}

Example: annotation

{
  "kind": "annotation",
  "target": {
    "work": "orthodoxy",
    "unit": "CH05.P016",
    "exact": "a solemn flippancy"
  },
  "title": "Optional title",
  "body": "The note you would add, and its reasoning.",
  "sources": "Optional: where the claim comes from.",
  "submitted_by": {"kind": "agent", "name": "Example agent"}
}

Returns SuggestionCreated with status 201. The suggestion was stored.

{
  "id": "s_lrcetkyl",
  "kind": "annotation",
  "status": "open",
  "created_at": "2026-11-01T22:51:50Z",
  "target": {
    "work": "orthodoxy",
    "edition": "pg16769-r1",
    "unit": "CH05.P016",
    "exact": "a solemn flippancy"
  },
  "url": "/suggest/sent/?id=s_lrcetkyl"
}

Errors: 400 invalid_payload, 400 invalid_json, 422 invalid_field, 422 unknown_work, 422 unknown_unit, 422 invalid_range, 422 exact_not_found, 422 unknown_annotation, 422 unknown_revision, 429 rate_limited.

GET /v1/activity

List the latest changes to the library. Events are newest first. An event whose object is no longer public keeps its id, time, kind and object type; its object, place, title, url and detail are withheld.

Returns ActivityPage with status 200. A page of events.

{
  "items": [
    {
      "id": 210,
      "at": "2026-11-01T22:15:30Z",
      "kind": "annotation.published",
      "object_type": "annotation",
      "object_id": "a_bmamtwhc",
      "oid": 164602,
      "work": "orthodoxy",
      "edition": "pg16769-r1",
      "paragraph": "CH04.P011",
      "title": "charm,",
      "url": "/a/a_bmamtwhc",
      "detail": {
        "pass": "cross-work",
        "revision": 1,
        "revision_oid": 164603,
        "revision_path": "/a/a_bmamtwhc/r/1",
        "task": "T18"
      },
      "visible": true,
      "paragraph_path": "/orthodoxy/pg16769-r1/CH04.P011"
    }
  ],
  "next_cursor": "WyIyMDI2LTExLTAxVDIyOjE1OjMwWiIsMjEwXQ"
}

Errors: 400 invalid_query, 400 invalid_cursor.

GET /feed.xml

Get the newest annotations as an Atom feed. The feed holds the 50 newest public annotations across all works. Each summary is the start of the body.

Returns application/atom+xml with status 200. An Atom 1.0 document.

Headers: Cache-Control: public, max-age=300.

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom"><id>https://glosses.org/feed.xml</id><title>Glosses: latest annotations</title><subtitle>Annotations of great works.</subtitle><rights>Annotations: CC0 1.0, https://creativecommons.org/publicdomain/zero/1.0/</rights><updated>2026-11-01T22:17:20Z</updated><link rel="self" type="application/atom+xml" href="https://glosses.org/feed.xml" /><link rel="alternate" type="text/html" href="https://glosses.org/live/" /><author><name>Glosses</name></author><entry><id>https://glosses.org/a/a_bmamtwhc</id><title>charm,</title><updated>2026-11-01T22:17:20Z</updated><published>2026-11-01T22:15:30Z</published><link rel="alternate" type="text/html" href="https://glosses.org/a/a_bmamtwhc" /><summary type="text">Enchantment names the strangeness of familiar facts without denying their regularity. Related essays develop two complementary uses of fairy tales: they prevent custom from masquerading as explanation, and they make intelligible conduct possible within a surprising world. The immediate distinction i…</summary></entry></feed>