New York Public Library Digital Collections API. Source docs: https://api.repo.nypl.org/. Note: NYPL states the Repo API is being deprecated and will no longer be available starting August 1st, 2026.
Printed by @kierandotai (kierandotai).
Quick Start
1. Install
See Install above.
2. Set Up Credentials
Get your API key from your API provider's developer portal. The key typically looks like a long alphanumeric string.
export NYPL_DIGITAL_COLLECTIONS_NYPL_TOKEN="<paste-your-key>"
You can also persist this in your config file at ~/.config/nypl-digital-collections-pp-cli/config.toml.
3. Verify Setup
nypl-digital-collections-pp-cli doctor
This checks your configuration and credentials.
4. Try Your First Command
nypl-digital-collections-pp-cli collections list
Usage
Run nypl-digital-collections-pp-cli --help for the full command reference and flag list.
Commands
collections
Manage collections
nypl-digital-collections-pp-cli collections get - Returns paginated child captures for a collection or subcollection/container UUID.nypl-digital-collections-pp-cli collections list - Returns paginated information about collections.
items
Manage items
nypl-digital-collections-pp-cli items get-counts - Returns collection item counts.nypl-digital-collections-pp-cli items get-details - Returns MODS for a capture UUID plus related capture information. UUID must belong to a valid capture.nypl-digital-collections-pp-cli items get-featured - Returns featured items.nypl-digital-collections-pp-cli items get-mets-alto - Returns METS ALTO for a given capture UUID.nypl-digital-collections-pp-cli items get-minified-alto - Returns minified ALTO for a given capture UUID.nypl-digital-collections-pp-cli items get-mods-captures - Returns MODS and capture information for a capture, item, container, or collection UUID.nypl-digital-collections-pp-cli items get-plain-text - Returns parsed plain text ALTO for a given capture UUID.nypl-digital-collections-pp-cli items get-rights - Returns rights profile information for a UUID.nypl-digital-collections-pp-cli items get-total - Returns the total number of digitized items.nypl-digital-collections-pp-cli items list-all-collection-captures - Returns all capture UUIDs, image IDs, item links, and titles for a capture, item, container, or collection UUID.nypl-digital-collections-pp-cli items list-captures - Returns capture UUIDs, image IDs, item links, and titles for an item, container, or collection UUID. Capture UUIDs are not valid input values.nypl-digital-collections-pp-cli items list-collection-captures - Returns capture UUIDs, image IDs, item links, and titles for a capture, item, container, or collection UUID.nypl-digital-collections-pp-cli items list-recent - Returns the most recently added captures.nypl-digital-collections-pp-cli items list-root - Returns all top-level UUIDs for collections and orphan items.nypl-digital-collections-pp-cli items lookup-identifier - Returns UUIDs for a given identifier type and identifier value such as local_image_id, local_bnumber, local_barcode, oclc, isbn, or lccn.nypl-digital-collections-pp-cli items search-digital - Returns results matching keywords anywhere in a MODS metadata record. Supports field-specific search, fuzzy/exact field type, optional filters, pagination, and public-domain filtering.
mods
Manage mods
nypl-digital-collections-pp-cli mods <uuid> - Returns MODS bibliographic data for a capture, item, container, or collection UUID.
Output Formats
# Human-readable table (default in terminal, JSON when piped)
nypl-digital-collections-pp-cli collections list
# JSON for scripting and agents
nypl-digital-collections-pp-cli collections list --json
# Filter to specific fields
nypl-digital-collections-pp-cli collections list --json --select id,name,status
# Dry run — show the request without sending
nypl-digital-collections-pp-cli collections list --dry-run
# Agent mode — JSON + compact + no prompts in one flag
nypl-digital-collections-pp-cli collections list --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Explicit retries - add
--idempotent to create retries when a no-op success is acceptable
- Confirmable -
--yes for explicit confirmation of destructive actions
- Piped input - write commands can accept structured input when their help lists
--stdin
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.
Health Check
nypl-digital-collections-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Config file: ~/.config/nypl-digital-collections-pp-cli/config.toml
Static request headers can be configured under headers; per-command header overrides take precedence.
Environment variables:
| Name | Kind | Required | Description |
|---|
NYPL_DIGITAL_COLLECTIONS_NYPL_TOKEN | per_call | Yes | Set to your API credential. |
Troubleshooting
Authentication errors (exit code 4)
- Run
nypl-digital-collections-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $NYPL_DIGITAL_COLLECTIONS_NYPL_TOKEN
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
Generated by CLI Printing Press