nulib · kdid · May 19, 2026 · Apr 20, 2026 · Apr 24, 2026 · Apr 27, 2026
diff --git a/README.md b/README.md
@@ -51,6 +51,22 @@ View and edit information about a specific Work in the Index.
 3. View JSON response at `https://USER_PREFIX.dev.rdc.library.northwestern.edu:3002/works/[WORK_ID]`
 4. View IIIF Manifest JSON response at `https://USER_PREFIX.dev.rdc.library.northwestern.edu:3002/works/[WORK_ID]?as=iiif`
 
+### IIIF content search
+
+IIIF Presentation responses expose [IIIF Content Search 2.0](https://iiif.io/api/search/2.0/) services for transcription annotations:
+
+- Work manifests include a `SearchService2` entry for `https://USER_PREFIX.dev.rdc.library.northwestern.edu:3002/works/[WORK_ID]/search?as=iiif`
+- File set canvases include a `SearchService2` entry for `https://USER_PREFIX.dev.rdc.library.northwestern.edu:3002/file-sets/[FILE_SET_ID]/search?as=iiif`
+
+To search transcription text, include a non-empty `q` parameter:
+
+```shell
+curl "https://USER_PREFIX.dev.rdc.library.northwestern.edu:3002/works/[WORK_ID]/search?as=iiif&q=[QUERY]"
+curl "https://USER_PREFIX.dev.rdc.library.northwestern.edu:3002/file-sets/[FILE_SET_ID]/search?as=iiif&q=[QUERY]"
+```
+
+Both endpoints return a IIIF `AnnotationPage` whose `items` target the matching work canvas or file set canvas. Requests without `as=iiif` or a non-empty `q` return `400`.
+
 For help debugging/inspecting, JavaScript `console` messages are written to: `dc-api-v2/dc-api.log`
 
 ### DC

diff --git a/api/dependencies/package-lock.json b/api/dependencies/package-lock.json
diff --git a/api/dependencies/package.json b/api/dependencies/package.json
@@ -1,6 +1,6 @@
 {
   "name": "dc-api-dependencies",
-  "version": "2.10.10",
+  "version": "2.11.0",
   "description": "NUL Digital Collections API Dependencies",
   "repository": "https://github.com/nulib/dc-api-v2",
   "author": "nulib",

diff --git a/api/package-lock.json b/api/package-lock.json
diff --git a/api/package.json b/api/package.json
@@ -1,6 +1,6 @@
 {
   "name": "dc-api-build",
-  "version": "2.10.10",
+  "version": "2.11.0",
   "description": "NUL Digital Collections API Build Environment",
   "repository": "https://github.com/nulib/dc-api-v2",
   "author": "nulib",

diff --git a/api/src/api/opensearch.js b/api/src/api/opensearch.js
@@ -27,6 +27,7 @@ async function getWorkFileSets(workId, opts = {}) {
   const {
     allowPrivate = false,
     allowUnpublished = false,
+    annotationsQuery = null,
     role = null,
     source = null,
     sortBy = null,
@@ -52,6 +53,11 @@ async function getWorkFileSets(workId, opts = {}) {
   if (role) {
     mustClauses.push({ term: { role: role } });
   }
+  if (annotationsQuery) {
+    mustClauses.push({
+      match_phrase: { "annotations.content": annotationsQuery },
+    });
+  }
 
   const searchBody = {
     size: 10000,

diff --git a/api/src/api/pagination.js b/api/src/api/pagination.js
@@ -4,7 +4,15 @@ const {
 } = require("lz-string");
 const { defaultSearchSize } = require("../environment");
 
-const encodeFields = ["query", "size", "sort", "fields", "_source"];
+const encodeFields = [
+  "query",
+  "size",
+  "sort",
+  "fields",
+  "collapse",
+  "aggs",
+  "_source",
+];
 
 async function decodeSearchToken(token) {
   return JSON.parse(await decompress(token));
@@ -17,6 +25,7 @@ async function encodeSearchToken(models, body, format, options) {
       token.body[field] = body[field];
     }
   }
+  if (token.body.aggs?._pagination) delete token.body.aggs._pagination;
   return await compress(JSON.stringify(token));
 }
 
@@ -55,6 +64,13 @@ class Paginator {
     this.options = options;
   }
 
+  async pageResponseInfo(responseBody, opts = {}) {
+    return this.pageInfo(responseBody.hits.total.value, {
+      aggregatedCount: responseBody.hits.collapsed?.value,
+      ...opts,
+    });
+  }
+
   async pageInfo(count, opts = {}) {
     let url = new URL(this.route, this.baseUrl);
     let searchToken;
@@ -74,15 +90,18 @@ class Paginator {
     }
 
     const queryStringParameters =
-      this.options?.parameterOverrides || this.options?.queryStringParameters;
+      this.options?.parameterOverrides ||
+      this.options?.queryStringParameters ||
+      {};
     if (typeof queryStringParameters === "object") {
       for (const param in queryStringParameters) {
         url.searchParams.set(param, queryStringParameters[param]);
       }
     }
 
-    const prev = prevPage(this.body, count);
-    const next = nextPage(this.body, count);
+    const aggregatedCount = opts?.aggregatedCount || count;
+    const prev = prevPage(this.body, aggregatedCount);
+    const next = nextPage(this.body, aggregatedCount);
     url.searchParams.delete("from");
 
     let result = {
@@ -91,9 +110,15 @@ class Paginator {
       limit: size(this.body),
       offset: from(this.body),
       total_hits: count,
-      total_pages: maxPage(this.body, count),
+      total_pages: maxPage(this.body, aggregatedCount),
       format: this.format,
     };
+    if (this.body.collapse) {
+      result.collapsed_by = {
+        field: this.body.collapse.field,
+        total_hits: aggregatedCount,
+      };
+    }
     if (opts.includeOptions) {
       result.options = this.options;
     }

diff --git a/api/src/api/request/pipeline.js b/api/src/api/request/pipeline.js
@@ -104,8 +104,20 @@ module.exports = class RequestPipeline {
     return this;
   }
 
+  addCardinality() {
+    if (this.searchContext.collapse) {
+      this.searchContext.aggs ||= {};
+      this.searchContext.aggs.__pagination = {
+        cardinality: {
+          field: this.searchContext.collapse.field,
+        },
+      };
+    }
+    return this;
+  }
+
   toJson() {
-    this.addNeuralModelId();
+    this.addNeuralModelId().addCardinality();
     return JSON.stringify(sortJson(this.searchContext));
   }
 };
diff --git a/api/src/api/response/iiif/annotations.js b/api/src/api/response/iiif/annotations.js
@@ -1,69 +1,28 @@
 const { dcApiEndpoint } = require("../../../environment");
-const { getWorkFileSets } = require("../../opensearch");
+const {
+  buildAnnotationTarget,
+  buildSearchAnnotationBody,
+} = require("./search-helpers");
 
-async function transform(response, options = {}) {
-  const body = JSON.parse(response.body);
-  const fileSet = body._source;
-  const annotations = fileSet?.annotations ?? [];
-
-  const workId = fileSet.work_id;
-  const fileSetId = body._id;
-  const fileSetIndex = await getFileSetIndex(workId, fileSetId, options);
-
-  const canvasId = `${dcApiEndpoint()}/works/${workId}?as=iiif/canvas/${fileSetIndex}`;
-  const annotationPageId = `${dcApiEndpoint()}/file-sets/${
-    fileSet.id
-  }/annotations?as=iiif`;
-
-  // Build annotation items - filter for transcriptions only
-  // We currently will only have one annotation and it's a transcription
-  const items = annotations
-    .filter((annotation) => annotation.type === "transcription")
-    .map((annotation, idx) => {
-      const annotationId = `${annotationPageId}/a${idx}`;
-      return {
-        id: annotationId,
-        type: "Annotation",
-        motivation: "commenting",
-        body: {
-          type: "TextualBody",
-          value: annotation.content,
-          format: "text/plain",
-          language: annotation.language || "en",
-        },
-        target: canvasId,
-      };
-    });
-
-  const annotationPage = {
-    "@context": "http://iiif.io/api/presentation/3/context.json",
-    id: annotationPageId,
-    type: "AnnotationPage",
-    items: items,
-  };
+function transform(annotation, fileSet) {
+  const canvasId = `${dcApiEndpoint()}/file-sets/${fileSet.id}?as=iiif`;
+  const annotationId = `${dcApiEndpoint()}/annotations/${
+    annotation.id
+  }?as=iiif`;
 
   return {
     statusCode: 200,
-    headers: {
-      "content-type": "application/json",
-    },
-    body: JSON.stringify(annotationPage),
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      "@context": "http://iiif.io/api/presentation/3/context.json",
+      id: annotationId,
+      type: "Annotation",
+      // We have hardcoded motivations here, but in the future we may want to make this more dynamic based on the annotation type
+      motivation: ["contentState", "commenting"],
+      body: buildSearchAnnotationBody(annotation),
+      target: buildAnnotationTarget(canvasId, fileSet.work_id),
+    }),
   };
 }
 
-async function getFileSetIndex(workId, fileSetId, options) {
-  const fileSetsResponse = await getWorkFileSets(workId, {
-    allowPrivate: options.allowPrivate,
-    allowUnpublished: options.allowUnpublished,
-    role: "Access",
-    sortBy: "rank",
-  });
-
-  const fileSetBody = JSON.parse(fileSetsResponse.body);
-  const hits = fileSetBody?.hits?.hits || [];
-
-  const index = hits.findIndex((hit) => hit._source.id === fileSetId);
-
-  return index;
-}
 module.exports = { transform };