Last updated: 2026-07-07
\nMetaMuseum exposes `/api/activity` as an ActivityStreams 2.0 change feed with an embedded Linked Art projection on each activity item. The feed is designed for downstream collection-data consumers that need incremental synchronization while preserving Linked Art event semantics.
\n| Endpoint | Purpose |
\n|---|---|
\n| `/api/activity` | Global ActivityStreams `OrderedCollectionPage` over local write-audit, deletion, and semantic record activities. |
\n| `/api/activity/collection` | IIIF Change Discovery-compatible `OrderedCollection` with mandatory `first` and `last` page references. |
\n| `/api/activity/page/{page}` | Fixed ascending `OrderedCollectionPage` resources for walk-back harvesters. |
\n| `/api/activity/object/{encodedObjectId}` | Object-scoped `OrderedCollectionPage` for one Linked Art object URI. |
\n| `/api/activity/readiness` | External-consumer readiness ledger populated by declared feed reads. |
\n| `/api/activity/subscriptions` | Durable callback subscription registry and verification target for downstream aggregators. |
\n| `/api/providers/capabilities` | Provider and activity-syndication capability document, including discovery rels, endpoint templates, filters, and callback signing headers. |
\nAll activity endpoints support `GET` and `OPTIONS`, CORS, and `application/activity+json`.
\nEach `/api/activity` cursor-feed `orderedItems[]` entry is an ActivityStreams activity with:
\nFor semantic collection events, `linkedArt` preserves event-centric fields such as `type`, `timespan`, `_complete`, names, classifications, object-specific target links (`produced`, `created`, `modified`, `destroyed`, `removed`, `encountered`, `formed`, `dissolved`), `used_specific_object`, and `carried_out_by` when those fields are valid for the activity class. `Set` collection records emit `Creation`/`created` rows, not physical `Production` rows, and record detail responses preserve `member_of` on the member record rather than inventing inverse `member[]` lists on the Set. Provenance wrapper activities also preserve relative `before`/`after` ordering and bundled `part[]` entries such as `Encounter`, `Acquisition`, `RightAcquisition`, `TransferOfCustody`, indeterminate `Transfer`, `Move`, and `Payment`, including nested find/rediscovery, title-transfer, rights-establishment/invalidation, percentage ownership shares, copyright, custody-transfer, unknown-transfer, movement origin/destination, multiple-owner, agent, exchange, loan, theft/loss, and commission/service payment details. Auction activities preserve auction-house/place classifications, auction-of-lot identifiers, lot `Set` `used_specific_object` values, `part_of` links to the overall auction, and provenance purchases `caused_by` the lot auction. Exhibition activities preserve exhibiting classifications, venue and organizer metadata, source descriptions, object-list `Set` links, concept `PropositionalObject` influence, and travelling-exhibition `part_of` links. Conservation coverage keeps condition assessments as `AttributeAssignment` rows with `assigned_property` and `assigned` condition types, separate from conservation `Modification` rows with technique, actor, description, timespan, and shared project `part_of` links. `Birth` and `Death` projections intentionally suppress `carried_out_by` and `used_specific_object`, matching the Linked Art activity-class restrictions.
\nDefault `/api/activity` cursor-feed responses and IIIF Change Discovery pages use the same partner-facing projection: valid UTC `endTime`, dereferenceable MetaMuseum `object.id` values, optional `object.sourceId` with the stored/provider record id when the projected id differs, `object.activityHref`, `source.kind`, and provider metadata. Default responses collapse duplicate rows for the same projected `object.id` to one latest-change harvest item, preferring deletion, audit, and `record-backfill` publication signals over historic `record-semantic` rows; explicit `source=` filters still expose source-specific rows for diagnostics and evidence checks. The cursor feed keeps embedded `linkedArt` by default, while IIIF Change Discovery pages are thin by default for immutable-page harvesters. Add `embed=linked-art` to a collection or page URL to include the richer `linkedArt` projection in fixed-page responses. Partners can verify the event handoff by reading `type=Update`, then dereferencing the first row's `linkedArt.id`; the returned `/api/events/...` entity should keep the same id, `_complete: false`, and source-preserving `equivalent[]`.
\nThe feed includes a conservative `record-backfill` source: if a stored record is not already represented by an audit or deletion activity, MetaMuseum emits one thin `Create` publication activity for that record. Semantic collection events such as production, creation, encounter, or custody transfer remain separate and do not suppress this bootstrap publication row, because external harvesters need a current-record publication signal as well as historic object events. Backfill timestamps prefer record/source update or import metadata such as `_source.importedAt`; for initial production seed rows, these are import/republication times rather than original museum object-change times. Unresolved timestamps still fall back to the epoch marker described below. Activity objects also carry an `equivalent[]` array with cross-dataset `equivalent[]` identifiers derived from stored `equivalent[]`, provider record URLs, provider collection URLs, and provider object Wikidata URLs when available.
\nWhen an activity `object.id` dereferences through `/api/records/{id}`, the detail response serializes the record `id` as the canonical HTTP(S) detail URL, aligns the embedded record `_links.self.href` with that URL, and exposes the stored/provider identity in `equivalent[]`. This keeps a dereferenceable `object.id` on MetaMuseum Linked Art records while preserving the source record and import identity. Record detail responses also emit HTTP `Link` headers for autodiscovery: `rel="http://iiif.io/api/discovery/1#activity"` points at `/api/activity/collection`, while `rel="alternate"` points at the cursor feed and object-scoped feed.
\nThe feed extracts semantic events from these stored Linked Art record properties:
\n| Record property | Linked Art event type | ActivityStreams type |
\n|---|---|---|
\n| `produced_by` | `Production` | `Create` |
\n| `created_by` | `Creation` | `Create` |
\n| `attributed_by` | `AttributeAssignment` | `Update` |
\n| `modified_by` | `Modification` | `Update` |
\n| `destroyed_by` | `Destruction` | `Update` |
\n| `removed_by` | `PartRemoval` | `Create` |
\n| `encountered_by` | `Encounter` | `Update` |
\n| `formed_by` | `Formation` | `Create` |
\n| `dissolved_by` | `Dissolution` | `Update` |
\n| `born` | `Birth` | `Create` |
\n| `died` | `Death` | `Update` |
\n| `transferred_title_of` | `TransferOfTitle` | `Update` |
\n| `transferred_custody_of` | `TransferOfCustody` | `Update` |
\n| `used_for` | `Activity` | `Update` |
\nSemantic `Destruction`, `Dissolution`, and `Death` describe lifecycle facts inside the Linked Art record, so MetaMuseum publishes them as ActivityStreams `Update` rows. ActivityStreams `Delete` remains reserved for real record/tombstone deletions from the deletion evidence pipeline, especially genuine upstream `404` or `410` cases.
\nWrite-audit and deletion events still emit a generic Linked Art `Activity` projection so every activity item has a Linked Art-facing payload, even when the source event is operational rather than semantic.
\nConsumers may use:
\nThe default page size is `25` when `limit` is absent, and explicit `limit` values are clamped to `1..100`.
\nThe canonical `next` link prefers cursor sync only when the page boundary has a valid non-fallback timestamp. If a source event carries an invalid timestamp, `next` falls back to the offset-based `nextPage` link instead of emitting an unusable cursor. The `nextPage` alias remains offset-based for existing consumers.
\nThis profile now includes a first IIIF Change Discovery API 1.0 compatibility layer. `/api/activity/collection` exposes a spec-shaped `OrderedCollection` with mandatory `first` and `last` page references, including the mandatory collection `last` link, and `/api/activity/page/{page}` exposes fixed ascending `OrderedCollectionPage` resources so IIIF/LOUD harvesters can start at `last`, walk `prev`, and stop at their last processed timestamp. Declared consumer IDs sent to the collection and page endpoints are recorded in the same readiness ledger as cursor-feed reads; page reads also merge the concrete activity types observed on that page. The original descending cursor API remains documented as a MetaMuseum extension for tail-following consumers.
\nExample walk-back seed:
\n\ncurl "https://www.metamuseum.org/api/activity/collection?limit=100&provider=met" \\\n -H "accept: application/activity+json"\nEach fixed page lists older activities first and newer activities last, matching the Change Discovery consumption model. Fixed pages omit absent `prev` and `next` links, normalize non-parseable source times to a valid UTC fallback with the original value preserved under `extensions.sourceEndTime`, and keep record-backed `object.id` values dereferenceable by pointing them at `/api/records/{encodedSourceRecordId}`. Epoch fallback timestamps are structurally valid but are not treated as production-quality incremental-sync evidence because they sort as the oldest possible changes; the evidence-grade production consumer run should wait for provider backfill with real event, import, or republication times and populated reconciliation hooks. Filter parameters such as `provider`, `type`, `source`, `object`, `since`, and `until` are preserved across collection, page, and cursor URLs; `embed=linked-art` is preserved across fixed-page traversal when requested.
\nOpen partner compatibility work:
\nPartner-owned consumers identify themselves with `x-linked-art-consumer-id` when reading `/api/activity`, `/api/activity/collection`, `/api/activity/page/{page}`, or an object-scoped feed. A consumer counts toward strict evidence only after real feed-read telemetry, activity-type coverage, durable subscription evidence, callback verification, and the refreshed syndication-evidence packet are present. Community outreach and placeholder IDs remain context only.
\nPartner onboarding steps and copy/paste commands live in activity-stream-partner-quickstart.md(activity-stream-partner-quickstart.md).
\nVerification:
\n\nnode --import tsx --test --test-concurrency=1 tests/api/activity.test.ts tests/api/activity-as2.test.ts\npnpm activity:syndication:evidence\n