{"id":"providers/smithsonian-open-access","relativePath":"providers/smithsonian-open-access.md","title":"Smithsonian Open Access Integration Plan","markdown":"# Smithsonian Open Access Integration Plan\n\nStatus: Landed + constraint-hardened (B5 provider slice) \nUpdated: May 30, 2026\n\n## Official sources\n\n- API docs landing: \n- API key signup: \n- Open Access program overview: \n\n## Key platform facts (from official docs)\n\n- Smithsonian Open Access API requires an `api_key` for endpoint access.\n- Core endpoints:\n - `GET /openaccess/api/v1.0/search`\n - `GET /openaccess/api/v1.0/category/:cat/search`\n - `GET /openaccess/api/v1.0/content/:id`\n - `GET /openaccess/api/v1.0/terms/:category`\n - `GET /openaccess/api/v1.0/stats`\n- Search paging:\n - `start` (offset)\n - `rows` (1..1000, default 10)\n - `sort`: `relevancy|id|newest|updated|random`\n- Route validation keeps `rowGroup` explicit and enum-limited to `objects|archives`.\n- Route validation keeps `category` explicit and enum-limited to official category paths.\n\n## Integration goals\n\n- Add Smithsonian as a first-class B5 provider under `provider-interface`.\n- Preserve canonical Linked Art JSON-LD at storage boundary (`SourceRecord` + `_source.raw`).\n- Keep API-key handling secure (env-only, no logging, no persistence).\n\n## Proposed implementation slice\n\n### Adapter (implemented)\n\n- `src/adapters/smithsonian.ts`\n - profile descriptor\n - search request builder (`q/start/rows/sort/type/row_group`)\n - content fetch by `id/url`\n - normalizer into project record/artwork boundaries\n\n### Routes (implemented)\n\n- `GET /api/smithsonian/profile`\n- `POST /api/smithsonian/search`\n- `POST /api/smithsonian/content`\n- `POST /api/smithsonian/import`\n\n### UI (implemented)\n\n- add `smithsonian` source toggle in `/explore`\n- provider attribution + rights/reuse display on results/details\n\n## Env configuration\n\n- `SMITHSONIAN_API_BASE` (default: `https://api.si.edu/openaccess/api/v1.0`)\n- `SMITHSONIAN_API_KEY` (required for live endpoint calls)\n\n## Security requirements\n\n- Never commit/share `SMITHSONIAN_API_KEY`.\n- Never emit the key in logs or error responses.\n- Keep outbound calls server-side only (no client-exposed key).\n\n## Standards mapping + tests\n\nRequired rounds (minimum): object/provenance/shared-structure + protocol/search rounds.\n\nRequired tests (failing-first):\n\n- `tests/adapters/smithsonian.test.ts`\n- `tests/api/smithsonian/profile.test.ts`\n- `tests/api/smithsonian/search.test.ts`\n- `tests/api/smithsonian/content.test.ts`\n- `tests/api/smithsonian/import.test.ts`\n\nProtocol checks (B8):\n\n- OPTIONS/CORS behavior on new routes\n- response shape conformance\n- URI opacity + array-cardinality safety where applicable\n\n## Exit criteria\n\n- Adapter + routes + tests green.\n- `/explore` can search/import Smithsonian records.\n- PR includes Standards Mapping note with round + fixture anchor coverage.\n\n## Constraint hardening notes\n\n- `SMITHSONIAN_API_KEY` is required for search/content/import fetches to Smithsonian endpoints.\n- `/api/smithsonian/search` route-level schema validates official pagination fields:\n - `start` integer `>= 0`\n - `rows` integer `1..1000`\n- Backward-compatible aliases (`offset`/`limit`) remain accepted for older internal callers, but `start`/`rows` are canonical.\n","sections":[{"level":2,"heading":"Official sources","anchor":"official-sources"},{"level":2,"heading":"Key platform facts (from official docs)","anchor":"key-platform-facts-from-official-docs"},{"level":2,"heading":"Integration goals","anchor":"integration-goals"},{"level":2,"heading":"Proposed implementation slice","anchor":"proposed-implementation-slice"},{"level":3,"heading":"Adapter (implemented)","anchor":"adapter-implemented"},{"level":3,"heading":"Routes (implemented)","anchor":"routes-implemented"},{"level":3,"heading":"UI (implemented)","anchor":"ui-implemented"},{"level":2,"heading":"Env configuration","anchor":"env-configuration"},{"level":2,"heading":"Security requirements","anchor":"security-requirements"},{"level":2,"heading":"Standards mapping + tests","anchor":"standards-mapping-tests"},{"level":2,"heading":"Exit criteria","anchor":"exit-criteria"},{"level":2,"heading":"Constraint hardening notes","anchor":"constraint-hardening-notes"}],"html":"

Smithsonian Open Access Integration Plan

\n

Status: Landed + constraint-hardened (B5 provider slice)

\n

Updated: May 30, 2026

\n

Official sources

\n
  • API docs landing: <https://api.si.edu/openaccess/docs/>
  • API key signup: <https://api.data.gov/signup/>
  • Open Access program overview: <https://www.si.edu/openaccess>
\n

Key platform facts (from official docs)

\n
  • Smithsonian Open Access API requires an `api_key` for endpoint access.
  • Core endpoints:
  • `GET /openaccess/api/v1.0/search`
  • `GET /openaccess/api/v1.0/category/:cat/search`
  • `GET /openaccess/api/v1.0/content/:id`
  • `GET /openaccess/api/v1.0/terms/:category`
  • `GET /openaccess/api/v1.0/stats`
  • Search paging:
  • `start` (offset)
  • `rows` (1..1000, default 10)
  • `sort`: `relevancy|id|newest|updated|random`
  • Route validation keeps `rowGroup` explicit and enum-limited to `objects|archives`.
  • Route validation keeps `category` explicit and enum-limited to official category paths.
\n

Integration goals

\n
  • Add Smithsonian as a first-class B5 provider under `provider-interface`.
  • Preserve canonical Linked Art JSON-LD at storage boundary (`SourceRecord` + `_source.raw`).
  • Keep API-key handling secure (env-only, no logging, no persistence).
\n

Proposed implementation slice

\n

Adapter (implemented)

\n
  • `src/adapters/smithsonian.ts`
  • profile descriptor
  • search request builder (`q/start/rows/sort/type/row_group`)
  • content fetch by `id/url`
  • normalizer into project record/artwork boundaries
\n

Routes (implemented)

\n
  • `GET /api/smithsonian/profile`
  • `POST /api/smithsonian/search`
  • `POST /api/smithsonian/content`
  • `POST /api/smithsonian/import`
\n

UI (implemented)

\n
  • add `smithsonian` source toggle in `/explore`
  • provider attribution + rights/reuse display on results/details
\n

Env configuration

\n
  • `SMITHSONIAN_API_BASE` (default: `https://api.si.edu/openaccess/api/v1.0`)
  • `SMITHSONIAN_API_KEY` (required for live endpoint calls)
\n

Security requirements

\n
  • Never commit/share `SMITHSONIAN_API_KEY`.
  • Never emit the key in logs or error responses.
  • Keep outbound calls server-side only (no client-exposed key).
\n

Standards mapping + tests

\n

Required rounds (minimum): object/provenance/shared-structure + protocol/search rounds.

\n

Required tests (failing-first):

\n
  • `tests/adapters/smithsonian.test.ts`
  • `tests/api/smithsonian/profile.test.ts`
  • `tests/api/smithsonian/search.test.ts`
  • `tests/api/smithsonian/content.test.ts`
  • `tests/api/smithsonian/import.test.ts`
\n

Protocol checks (B8):

\n
  • OPTIONS/CORS behavior on new routes
  • response shape conformance
  • URI opacity + array-cardinality safety where applicable
\n

Exit criteria

\n
  • Adapter + routes + tests green.
  • `/explore` can search/import Smithsonian records.
  • PR includes Standards Mapping note with round + fixture anchor coverage.
\n

Constraint hardening notes

\n
  • `SMITHSONIAN_API_KEY` is required for search/content/import fetches to Smithsonian endpoints.
  • `/api/smithsonian/search` route-level schema validates official pagination fields:
  • `start` integer `>= 0`
  • `rows` integer `1..1000`
  • Backward-compatible aliases (`offset`/`limit`) remain accepted for older internal callers, but `start`/`rows` are canonical.
","updatedAt":"2018-10-20T01:46:40.000Z","checksum":"db1ffa4cab027620662f30f3298f9fc1de983ddbb7858a2071efe7e59afc410c","checksumPrefix":"db1ffa4cab02","anchorCount":12,"lineCount":98,"rawUrl":"/api/docs/content?path=providers%2Fsmithsonian-open-access.md","htmlUrl":"/docs?doc=providers%2Fsmithsonian-open-access.md","apiUrl":"/api/docs/content?path=providers%2Fsmithsonian-open-access.md"}