{"id":"linked-art/activity-stream-partner-quickstart","relativePath":"linked-art/activity-stream-partner-quickstart.md","title":"ActivityStreams Partner Quickstart","markdown":"# ActivityStreams Partner Quickstart\n\nLast updated: 2026-07-07\n\nThis quickstart helps an external partner read the MetaMuseum ActivityStreams feed. It is onboarding documentation only. It does not count as external adoption evidence until a real partner-owned consumer ID, public feed read, durable HTTPS subscription, recent 2xx callback verification, and refreshed syndication evidence packet are recorded.\n\n## What To Ask For\n\nAsk the partner for:\n\n- A stable partner-owned consumer ID, such as `museum-reader-prod`.\n- The system or organization that owns that consumer ID.\n- A public HTTPS callback URL if they can receive activity notifications.\n- A contact who can confirm observed activity types and callback results.\n- A real evidence reference, such as an issue, ticket, log export, or email thread.\n\nDo not use demo, fixture, local, placeholder, sample, smoke, test, localhost, private-network, or MetaMuseum-owned IDs as strict evidence.\n\n## Read The Feed\n\nUse the partner-owned ID in `x-linked-art-consumer-id`.\n\n```bash\ncurl \"https://www.metamuseum.org/api/activity?limit=100\" \\\n -H \"accept: application/activity+json\" \\\n -H \"x-linked-art-consumer-id: museum-reader-prod\"\n```\n\nFor strict adoption evidence, read each required activity type with the same\ndeclared header as well. If a type-filtered URL returns zero items, report that\nexplicitly so operators can distinguish missing feed content from missing\npartner coverage.\n\n```bash\ncurl \"https://www.metamuseum.org/api/activity?limit=100&type=Create\" \\\n -H \"accept: application/activity+json\" \\\n -H \"x-linked-art-consumer-id: museum-reader-prod\"\n\ncurl \"https://www.metamuseum.org/api/activity?limit=100&type=Update\" \\\n -H \"accept: application/activity+json\" \\\n -H \"x-linked-art-consumer-id: museum-reader-prod\"\n\ncurl \"https://www.metamuseum.org/api/activity?limit=100&type=Delete\" \\\n -H \"accept: application/activity+json\" \\\n -H \"x-linked-art-consumer-id: museum-reader-prod\"\n```\n\nThe response is an ActivityStreams `OrderedCollectionPage`. Each item includes:\n\n- `type`: `Create`, `Update`, or `Delete`\n- `object.id`: affected dereferenceable MetaMuseum Linked Art object URI\n- `object.sourceId`: original provider/stored object URI when it differs from `object.id`\n- `object.activityHref`: object-scoped feed URL\n- `object.equivalent[]`: reconciliation hooks such as provider URIs or Wikidata QIDs when available\n- `linkedArt`: embedded Linked Art JSON-LD projection; `linkedArt.id` is a dereferenceable `/api/events/{encodedSourceActivityId}` URL, embedded projections carry `_complete: false`, and `linkedArt.equivalent[]` preserves the source activity URI when available\n- `source.kind`: `audit`, `record-backfill`, `record-semantic`, or `deletion`\n- `endTime`: valid UTC sync timestamp; original placeholder times are retained under `extensions.sourceEndTime`\n- `nextCursor`: stable cursor for incremental sync\n\nDefault cursor-feed reads collapse record-backed diagnostic rows to the latest\nharvestable public row per object, matching the IIIF Change Discovery projection.\nUse `source=record-semantic` or another `source=` filter when you need the\nunderlying semantic diagnostic rows instead of the deduped partner view.\n\n## Verify Update Linked Art Event Dereference\n\nWhen `type=Update` returns at least one item, fetch the first row's\n`orderedItems[0].linkedArt.id`. The response should return HTTP `200` with the\nLinked Art JSON-LD context, `entity.id` equal to the requested URL,\n`entity._complete: false`, and `entity.equivalent[]` preserving the source\nactivity URI.\n\n```bash\ncurl \"https://www.metamuseum.org/api/activity?limit=100&type=Update\" \\\n -H \"accept: application/activity+json\" \\\n -H \"x-linked-art-consumer-id: museum-reader-prod\"\n\ncurl \"\" \\\n -H \"accept: application/ld+json\" \\\n -H \"x-linked-art-consumer-id: museum-reader-prod\"\n```\n\nIf `type=Update` is zero, report zero and skip this dereference check. If\n`type=Delete` is zero, report zero explicitly as well; MetaMuseum does not emit\nDelete rows until a genuine upstream `404` or `410` tombstone exists.\n\n## Cursor Sync\n\nRead the first page, store `nextCursor`, then request the next page with `cursor`.\n\n```bash\ncurl \"https://www.metamuseum.org/api/activity?limit=100&cursor=\" \\\n -H \"accept: application/activity+json\" \\\n -H \"x-linked-art-consumer-id: museum-reader-prod\"\n```\n\nUseful filters:\n\n- `type=Create`, `type=Update`, or `type=Delete`\n- `source=record-backfill`, `source=record-semantic`, `source=audit`, or `source=deletion`\n- `provider=met`, `provider=vanda`, `provider=museumsvictoria`, or another provider key\n- `object=`\n- `since=`\n- `until=`\n\nWhen `limit` is absent, the feed returns up to `25` items. Explicit limits are clamped to `1..100`. The canonical `next` link uses a cursor only when the page boundary has a valid timestamp; otherwise it falls back to the offset `nextPage` link instead of emitting a bad cursor.\n\n## IIIF Walk-Back Harvest\n\nFor IIIF Change Discovery-compatible consumers, discover the fixed-page collection first:\n\n```bash\ncurl \"https://www.metamuseum.org/api/activity/collection?limit=100\" \\\n -H \"accept: application/activity+json\" \\\n -H \"x-linked-art-consumer-id: museum-reader-prod\"\n```\n\nStart from `last.id`, process that page in reverse item order if your mirror wants newest-first application, then follow each page's `prev.id` until you reach a timestamp older than your last crawl. Send `x-linked-art-consumer-id` on the collection request and every page request; MetaMuseum records those walk-back reads in the same readiness ledger as cursor-feed reads, and page reads record the concrete activity types observed on that page. The page documents themselves list activities oldest-to-newest so the most recent activity on a page appears last, matching the IIIF Change Discovery API 1.0 consumption model. The same filters used by cursor sync, including `provider=`, are preserved in `first`, `last`, `prev`, and `next` links.\n\nDiscovery pages are thin by default: `linkedArt` is omitted, `endTime` is always a valid UTC timestamp, `object.equivalent[]` is present when stored records carry reconciliation hooks, and bare stored IDs are projected as dereferenceable `/api/records/{id}` object URLs with the original value preserved as `object.sourceId`. The cursor feed uses the same object/time projection while keeping `linkedArt` embedded. To include the richer Linked Art projection during traversal, add `embed=linked-art`:\n\n```bash\ncurl \"https://www.metamuseum.org/api/activity/collection?limit=100&embed=linked-art\" \\\n -H \"accept: application/activity+json\" \\\n -H \"x-linked-art-consumer-id: museum-reader-prod\"\n```\n\n## Object Feed\n\nFor one object, use the encoded object URI:\n\n```bash\ncurl \"https://www.metamuseum.org/api/activity/object/https%3A%2F%2Fexample.org%2Fobject%2F123?limit=100\" \\\n -H \"accept: application/activity+json\" \\\n -H \"x-linked-art-consumer-id: museum-reader-prod\"\n```\n\nRecord detail responses also advertise activity discovery with HTTP `Link`\nheaders. A client that dereferences `/api/records/{id}` can find:\n\n- `rel=\"http://iiif.io/api/discovery/1#activity\"` for `/api/activity/collection`\n- `rel=\"alternate\"` for the cursor feed and object-scoped activity feed\n\nThe same activity metadata is listed under `/api/providers/capabilities` in\n`activitySyndication`.\n\n## Register A Callback\n\nIf the partner can receive events, register an HTTPS callback:\n\n```bash\ncurl -X POST \"https://www.metamuseum.org/api/activity/subscriptions\" \\\n -H \"content-type: application/json\" \\\n -H \"accept: application/activity+json\" \\\n -H \"x-linked-art-consumer-id: museum-reader-prod\" \\\n --data '{\"callbackUrl\":\"https://partner.example.org/metamuseum/activity\",\"eventTypes\":[\"Create\",\"Update\",\"Delete\"],\"signingRequired\":true,\"signingSecretRef\":\"museum-reader-prod-v1\"}'\n```\n\nThe callback URL must be public HTTPS and owned by the partner. When signing is enabled, the subscription stores only `signingSecretRef`; the actual HMAC secret is exchanged out of band. Callback deliveries are signed over `.` with HMAC-SHA256 and include:\n\n- `x-metamuseum-signature`: `sha256=`\n- `x-metamuseum-signature-timestamp`: UTC signing timestamp\n\nA subscription row alone is not enough for strict evidence; it also needs recent 2xx verification.\n\n## Verify Locally After Partner Reads\n\nAfter a real partner reads the feed:\n\n```powershell\npnpm activity:adoption:matrix -- --base-url https://www.metamuseum.org --consumer-id museum-reader-prod\npnpm activity:subscription:verify -- --consumer-id museum-reader-prod --callback-url https://partner.example.org/metamuseum/activity --status-code 204 --verified-at --evidence-ref \npnpm activity:syndication:evidence\n```\n\nThe evidence packet remains blocked until `consumerOnboarding.rows` shows the same partner consumer has feed-read telemetry, Create/Update/Delete type coverage, a durable subscription, callback verification, and strict packet refresh proof.\n\n## Partner Response Template\n\n```text\nConsumer ID:\nOrganization/system:\nFeed read timestamp:\nType-specific read timestamps:\nObserved activity types:\nUpdate linkedArt.id dereference:\nUpdate linkedArt.id notes:\nObject feed tested:\nCallback URL:\nCallback event types:\nCallback verification status code:\nCallback verification timestamp:\nEvidence ref:\nContact:\n```\n","sections":[{"level":2,"heading":"What To Ask For","anchor":"what-to-ask-for"},{"level":2,"heading":"Read The Feed","anchor":"read-the-feed"},{"level":2,"heading":"Verify Update Linked Art Event Dereference","anchor":"verify-update-linked-art-event-dereference"},{"level":2,"heading":"Cursor Sync","anchor":"cursor-sync"},{"level":2,"heading":"IIIF Walk-Back Harvest","anchor":"iiif-walk-back-harvest"},{"level":2,"heading":"Object Feed","anchor":"object-feed"},{"level":2,"heading":"Register A Callback","anchor":"register-a-callback"},{"level":2,"heading":"Verify Locally After Partner Reads","anchor":"verify-locally-after-partner-reads"},{"level":2,"heading":"Partner Response Template","anchor":"partner-response-template"}],"html":"

ActivityStreams Partner Quickstart

\n

Last updated: 2026-07-07

\n

This quickstart helps an external partner read the MetaMuseum ActivityStreams feed. It is onboarding documentation only. It does not count as external adoption evidence until a real partner-owned consumer ID, public feed read, durable HTTPS subscription, recent 2xx callback verification, and refreshed syndication evidence packet are recorded.

\n

What To Ask For

\n

Ask the partner for:

\n
  • A stable partner-owned consumer ID, such as `museum-reader-prod`.
  • The system or organization that owns that consumer ID.
  • A public HTTPS callback URL if they can receive activity notifications.
  • A contact who can confirm observed activity types and callback results.
  • A real evidence reference, such as an issue, ticket, log export, or email thread.
\n

Do not use demo, fixture, local, placeholder, sample, smoke, test, localhost, private-network, or MetaMuseum-owned IDs as strict evidence.

\n

Read The Feed

\n

Use the partner-owned ID in `x-linked-art-consumer-id`.

\n
\ncurl "https://www.metamuseum.org/api/activity?limit=100" \\\n  -H "accept: application/activity+json" \\\n  -H "x-linked-art-consumer-id: museum-reader-prod"\n
\n

For strict adoption evidence, read each required activity type with the same

\n

declared header as well. If a type-filtered URL returns zero items, report that

\n

explicitly so operators can distinguish missing feed content from missing

\n

partner coverage.

\n
\ncurl "https://www.metamuseum.org/api/activity?limit=100&type=Create" \\\n  -H "accept: application/activity+json" \\\n  -H "x-linked-art-consumer-id: museum-reader-prod"\n\ncurl "https://www.metamuseum.org/api/activity?limit=100&type=Update" \\\n  -H "accept: application/activity+json" \\\n  -H "x-linked-art-consumer-id: museum-reader-prod"\n\ncurl "https://www.metamuseum.org/api/activity?limit=100&type=Delete" \\\n  -H "accept: application/activity+json" \\\n  -H "x-linked-art-consumer-id: museum-reader-prod"\n
\n

The response is an ActivityStreams `OrderedCollectionPage`. Each item includes:

\n
  • `type`: `Create`, `Update`, or `Delete`
  • `object.id`: affected dereferenceable MetaMuseum Linked Art object URI
  • `object.sourceId`: original provider/stored object URI when it differs from `object.id`
  • `object.activityHref`: object-scoped feed URL
  • `object.equivalent[]`: reconciliation hooks such as provider URIs or Wikidata QIDs when available
  • `linkedArt`: embedded Linked Art JSON-LD projection; `linkedArt.id` is a dereferenceable `/api/events/{encodedSourceActivityId}` URL, embedded projections carry `_complete: false`, and `linkedArt.equivalent[]` preserves the source activity URI when available
  • `source.kind`: `audit`, `record-backfill`, `record-semantic`, or `deletion`
  • `endTime`: valid UTC sync timestamp; original placeholder times are retained under `extensions.sourceEndTime`
  • `nextCursor`: stable cursor for incremental sync
\n

Default cursor-feed reads collapse record-backed diagnostic rows to the latest

\n

harvestable public row per object, matching the IIIF Change Discovery projection.

\n

Use `source=record-semantic` or another `source=` filter when you need the

\n

underlying semantic diagnostic rows instead of the deduped partner view.

\n

Verify Update Linked Art Event Dereference

\n

When `type=Update` returns at least one item, fetch the first row's

\n

`orderedItems[0].linkedArt.id`. The response should return HTTP `200` with the

\n

Linked Art JSON-LD context, `entity.id` equal to the requested URL,

\n

`entity._complete: false`, and `entity.equivalent[]` preserving the source

\n

activity URI.

\n
\ncurl "https://www.metamuseum.org/api/activity?limit=100&type=Update" \\\n  -H "accept: application/activity+json" \\\n  -H "x-linked-art-consumer-id: museum-reader-prod"\n\ncurl "<orderedItems[0].linkedArt.id>" \\\n  -H "accept: application/ld+json" \\\n  -H "x-linked-art-consumer-id: museum-reader-prod"\n
\n

If `type=Update` is zero, report zero and skip this dereference check. If

\n

`type=Delete` is zero, report zero explicitly as well; MetaMuseum does not emit

\n

Delete rows until a genuine upstream `404` or `410` tombstone exists.

\n

Cursor Sync

\n

Read the first page, store `nextCursor`, then request the next page with `cursor`.

\n
\ncurl "https://www.metamuseum.org/api/activity?limit=100&cursor=<nextCursor>" \\\n  -H "accept: application/activity+json" \\\n  -H "x-linked-art-consumer-id: museum-reader-prod"\n
\n

Useful filters:

\n
  • `type=Create`, `type=Update`, or `type=Delete`
  • `source=record-backfill`, `source=record-semantic`, `source=audit`, or `source=deletion`
  • `provider=met`, `provider=vanda`, `provider=museumsvictoria`, or another provider key
  • `object=<encoded object URI>`
  • `since=<ISO timestamp>`
  • `until=<ISO timestamp>`
\n

When `limit` is absent, the feed returns up to `25` items. Explicit limits are clamped to `1..100`. The canonical `next` link uses a cursor only when the page boundary has a valid timestamp; otherwise it falls back to the offset `nextPage` link instead of emitting a bad cursor.

\n

IIIF Walk-Back Harvest

\n

For IIIF Change Discovery-compatible consumers, discover the fixed-page collection first:

\n
\ncurl "https://www.metamuseum.org/api/activity/collection?limit=100" \\\n  -H "accept: application/activity+json" \\\n  -H "x-linked-art-consumer-id: museum-reader-prod"\n
\n

Start from `last.id`, process that page in reverse item order if your mirror wants newest-first application, then follow each page's `prev.id` until you reach a timestamp older than your last crawl. Send `x-linked-art-consumer-id` on the collection request and every page request; MetaMuseum records those walk-back reads in the same readiness ledger as cursor-feed reads, and page reads record the concrete activity types observed on that page. The page documents themselves list activities oldest-to-newest so the most recent activity on a page appears last, matching the IIIF Change Discovery API 1.0 consumption model. The same filters used by cursor sync, including `provider=`, are preserved in `first`, `last`, `prev`, and `next` links.

\n

Discovery pages are thin by default: `linkedArt` is omitted, `endTime` is always a valid UTC timestamp, `object.equivalent[]` is present when stored records carry reconciliation hooks, and bare stored IDs are projected as dereferenceable `/api/records/{id}` object URLs with the original value preserved as `object.sourceId`. The cursor feed uses the same object/time projection while keeping `linkedArt` embedded. To include the richer Linked Art projection during traversal, add `embed=linked-art`:

\n
\ncurl "https://www.metamuseum.org/api/activity/collection?limit=100&embed=linked-art" \\\n  -H "accept: application/activity+json" \\\n  -H "x-linked-art-consumer-id: museum-reader-prod"\n
\n

Object Feed

\n

For one object, use the encoded object URI:

\n
\ncurl "https://www.metamuseum.org/api/activity/object/https%3A%2F%2Fexample.org%2Fobject%2F123?limit=100" \\\n  -H "accept: application/activity+json" \\\n  -H "x-linked-art-consumer-id: museum-reader-prod"\n
\n

Record detail responses also advertise activity discovery with HTTP `Link`

\n

headers. A client that dereferences `/api/records/{id}` can find:

\n
  • `rel="http://iiif.io/api/discovery/1#activity"` for `/api/activity/collection`
  • `rel="alternate"` for the cursor feed and object-scoped activity feed
\n

The same activity metadata is listed under `/api/providers/capabilities` in

\n

`activitySyndication`.

\n

Register A Callback

\n

If the partner can receive events, register an HTTPS callback:

\n
\ncurl -X POST "https://www.metamuseum.org/api/activity/subscriptions" \\\n  -H "content-type: application/json" \\\n  -H "accept: application/activity+json" \\\n  -H "x-linked-art-consumer-id: museum-reader-prod" \\\n  --data '{"callbackUrl":"https://partner.example.org/metamuseum/activity","eventTypes":["Create","Update","Delete"],"signingRequired":true,"signingSecretRef":"museum-reader-prod-v1"}'\n
\n

The callback URL must be public HTTPS and owned by the partner. When signing is enabled, the subscription stores only `signingSecretRef`; the actual HMAC secret is exchanged out of band. Callback deliveries are signed over `<timestamp>.<raw JSON payload>` with HMAC-SHA256 and include:

\n
  • `x-metamuseum-signature`: `sha256=<hex digest>`
  • `x-metamuseum-signature-timestamp`: UTC signing timestamp
\n

A subscription row alone is not enough for strict evidence; it also needs recent 2xx verification.

\n

Verify Locally After Partner Reads

\n

After a real partner reads the feed:

\n
\npnpm activity:adoption:matrix -- --base-url https://www.metamuseum.org --consumer-id museum-reader-prod\npnpm activity:subscription:verify -- --consumer-id museum-reader-prod --callback-url https://partner.example.org/metamuseum/activity --status-code 204 --verified-at <ISO timestamp> --evidence-ref <real-proof-ref>\npnpm activity:syndication:evidence\n
\n

The evidence packet remains blocked until `consumerOnboarding.rows` shows the same partner consumer has feed-read telemetry, Create/Update/Delete type coverage, a durable subscription, callback verification, and strict packet refresh proof.

\n

Partner Response Template

\n
\nConsumer ID:\nOrganization/system:\nFeed read timestamp:\nType-specific read timestamps:\nObserved activity types:\nUpdate linkedArt.id dereference:\nUpdate linkedArt.id notes:\nObject feed tested:\nCallback URL:\nCallback event types:\nCallback verification status code:\nCallback verification timestamp:\nEvidence ref:\nContact:\n
","updatedAt":"2018-10-20T01:46:40.000Z","checksum":"6ea3aea16866eedf39659890c65fbf05ea7683ff2e74de9be1efa019b038bf88","checksumPrefix":"6ea3aea16866","anchorCount":9,"lineCount":196,"rawUrl":"/api/docs/content?path=linked-art%2Factivity-stream-partner-quickstart.md","htmlUrl":"/docs?doc=linked-art%2Factivity-stream-partner-quickstart.md","apiUrl":"/api/docs/content?path=linked-art%2Factivity-stream-partner-quickstart.md"}