Export Hypothesis annotations without losing the reply context

You can export Hypothesis annotations for a readable local record, but an export and an import serve different purposes. The Sidebar offers JSON, TXT, CSV, and HTML exports. JSON is the format Hypothesis can import, yet its importer brings in top-level annotations and page notes, not their replies. Imported annotations are also attributed to the importing account. If a discussion matters, keep a separate local record of who wrote each entry and which entry it answers. Hypothesis export and import help

Export the intended annotations

1. In the Hypothesis Sidebar, select the annotation scope you want to record, including the relevant group or Only Me view. Group selection matters because annotations can live in different groups. Hypothesis groups help
2. Open Share, then Export. Check the author dropdown before downloading. When the selected scope contains your annotations, it defaults to your own; the author counts help you see whose annotations are included. Choose the authors you intend to record. Hypothesis export and import help
3. Download JSON if you need a structured record or may later import the top-level entries. Choose HTML or TXT when your immediate need is reading, or CSV for a spreadsheet. Keep the original export alongside any discussion record you make from it. Hypothesis export and import help

Before sharing an archive, check its scope and contents. Hypothesis says annotations in the public layer are CC0, while annotations in groups, including publicly readable groups, and Only Me remain rights reserved by their authors. That annotation license does not establish permission to reproduce a quoted source passage. For a group archive, follow the group’s sharing policy and obtain permission where needed; do not assume an export grants blanket reuse rights. Hypothesis annotation license help

Read the relationships in JSON

The Hypothesis client’s JSON exporter source defines a wrapper with export_date, export_userid, client_version, and an annotations list. Inside an annotation, fields such as id, user, uri, references, and target selectors help answer different questions: which entry this is, who wrote it, what page it concerns, what earlier entries a reply refers to, and what passage an annotation targets when a selector is present. Inspect the fields in your file; do not assume every entry has a selected passage or every field is present. Hypothesis annotation schema

For a reply, references contains its thread ancestry. The last ID in that list identifies its immediate parent. That distinction matters when a search returns both direct replies and replies to those replies. A root entry may have no references field at all; do not turn an absent field into a claimed value from the original record. Hypothesis annotation schema

A read-only public API observation shows the distinction. The root annotation has ID 3vCwKl6MEeawvxceTcKgwQ and no references field in its returned JSON. A search for entries referencing that root returned four rows: two direct replies and one follow-up beneath each of them. In shortened form, the relationships are:

• Root 3vCwKl6…
  • Reply aZr74oBx… → follow-up rls0iKL9…
  • Reply 2tp4BnOK… → follow-up 1rXrEqL9…

The follow-up rls0iKL9… listed both the root and aZr74oBx… in references; aZr74oBx… was its immediate parent. Likewise, 1rXrEqL9… listed the root and 2tp4BnOK…, making 2tp4BnOK… its immediate parent. The downloadable public-thread metadata record preserves the full IDs and relationships from this observation without copying the discussion text. The search reported total: 4 and returned four rows for that query. It was a specific public-thread lookup, not a complete export of an account or group. Hypothesis API reference

Make a readable discussion record

For each entry you are permitted to retain, record its ID, original author label, page URI, and immediate parent ID. Add the selected quote or enough source context to identify the passage when your record and reuse rights allow it. Keep the entry’s text linked to that context. If a parent is missing from your material, label the relationship unresolved: the parent might be outside the records you collected, inaccessible to you, or unavailable. Its identity cannot be reconstructed from dates alone.

The three-entry practice JSON illustrates this with invented IDs: practice-root has references: [], practice-reply refers to practice-root, and practice-followup refers to both earlier IDs. That is three flat entries but one top-level annotation with two replies. The accompanying static practice reader shows the comments, original author labels, and parent links together. These are synthetic teaching files, not a Hypothesis export or evidence of a successful import.

If you instead plan to import, apply Hypothesis’s documented rule to the material first. In the three-entry practice structure, only practice-root is top-level, so one eligible top-level entry is the documented-rule prediction, not a tested import result. The two replies need the separate readable record if you want their relationships to remain visible. Import attribution will belong to the importer, so retain original author labels in that record rather than expecting the imported entries to carry them. Hypothesis export and import help

When a thread looks incomplete

First recheck the Sidebar scope and author choice. An export filtered to your own annotations can omit another person’s replies even when the selected discussion contains them. Hypothesis export and import help

Next check the format. The current client exporter source defines CSV headers for creation time, author, page title, URL, group, type, quote or description, comment, and tags; it does not include annotation IDs or references in those headers. A CSV alone therefore does not supply the parent links used in the example above. Inspect the actual file you received before relying on any field.

Finally, treat an unresolved API lookup as unresolved. A missing response does not by itself prove that an annotation was deleted; access and lookup scope can affect what is available. A targeted public query also cannot establish that every annotation in a group or account has been collected. Hypothesis API reference

Scope: The five-record thread was observed through read-only public API requests on October 7, 2026 KST. The export, CSV, licensing, and import details above come from the linked Hypothesis documentation and client source. No Sidebar export, GUI import, private-group test, or import of the synthetic practice files was performed.