Skip to content

Instantly share code, notes, and snippets.

@billdueber

billdueber/_prompt.md

Last active February 26, 2026 19:49
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save billdueber/29d9c7fe4ded8655677e8398ae14a50f to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save billdueber/29d9c7fe4ded8655677e8398ae14a50f to your computer and use it in GitHub Desktop.
Download ZIP
Digital Repo API
Raw
_prompt.md

Create a programming-langague-independent API for a modern headless archival digital repository for an academic research library. Start with an overall list of the major functions that need to be supported text that explains what the general functionality area covers, then list individual endpoints under each heading along with possible arguments and error conditions that would need to provide feedbasck via the return values.

Raw
claude_output.md

Digital Repository API Specification

Version 1.0.0

This document defines a language-independent REST API for a modern headless archival digital repository system designed for academic research libraries.

1. Collection Management

Purpose: Manage hierarchical collections that organize repository content. Collections can contain both items and sub-collections, enabling flexible organizational structures.

Endpoints

POST /api/v1/collections

Create a new collection.

Arguments:

  • title (string, required): Collection title
  • description (string, optional): Collection description
  • parent_id (string, optional): Parent collection UUID
  • metadata (object, optional): Custom metadata fields
  • visibility (enum, required): public, restricted, private
  • access_policy_id (string, optional): Associated access policy UUID

Returns:

  • 201 Created: Collection object with UUID
  • 400 Bad Request: Invalid input data
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Parent collection not found
  • 409 Conflict: Collection with same identifier already exists

GET /api/v1/collections/{collection_id}

Retrieve collection details.

Arguments:

  • collection_id (string, required): Collection UUID
  • include_items (boolean, optional): Include item list (default: false)
  • include_subcollections (boolean, optional): Include subcollection list (default: true)
  • page (integer, optional): Page number for pagination
  • per_page (integer, optional): Items per page (max: 100)

Returns:

  • 200 OK: Collection object
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Access denied
  • 404 Not Found: Collection not found

PUT /api/v1/collections/{collection_id}

Update collection metadata.

Arguments:

  • collection_id (string, required): Collection UUID
  • title (string, optional): Updated title
  • description (string, optional): Updated description
  • metadata (object, optional): Updated metadata fields
  • visibility (enum, optional): Updated visibility

Returns:

  • 200 OK: Updated collection object
  • 400 Bad Request: Invalid input data
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Collection not found
  • 409 Conflict: Update conflicts with existing data

DELETE /api/v1/collections/{collection_id}

Delete a collection.

Arguments:

  • collection_id (string, required): Collection UUID
  • cascade (boolean, optional): Delete child items/collections (default: false)

Returns:

  • 204 No Content: Collection deleted
  • 400 Bad Request: Cannot delete non-empty collection without cascade
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Collection not found
  • 409 Conflict: Collection has active preservation actions

GET /api/v1/collections

List and search collections.

Arguments:

  • query (string, optional): Search query
  • parent_id (string, optional): Filter by parent collection
  • visibility (enum, optional): Filter by visibility
  • sort (enum, optional): title, created_at, updated_at, item_count
  • order (enum, optional): asc, desc
  • page (integer, optional): Page number
  • per_page (integer, optional): Items per page (max: 100)

Returns:

  • 200 OK: Array of collection objects with pagination metadata
  • 400 Bad Request: Invalid query parameters
  • 401 Unauthorized: Authentication required

2. Item Management

Purpose: Manage individual repository items (digital objects). Items are the fundamental units of content, containing metadata and associated files/bitstreams.

Endpoints

POST /api/v1/items

Create a new repository item.

Arguments:

  • title (string, required): Item title
  • description (string, optional): Item description
  • collection_id (string, required): Parent collection UUID
  • metadata (object, required): Metadata according to schema
  • item_type (string, required): Item type identifier
  • visibility (enum, required): public, restricted, private, embargo
  • embargo_date (datetime, optional): Embargo lift date
  • access_policy_id (string, optional): Access policy UUID

Returns:

  • 201 Created: Item object with UUID
  • 400 Bad Request: Invalid input or metadata validation failure
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Collection not found
  • 422 Unprocessable Entity: Metadata schema validation failed

GET /api/v1/items/{item_id}

Retrieve item details.

Arguments:

  • item_id (string, required): Item UUID
  • include_files (boolean, optional): Include file list (default: true)
  • include_metadata (boolean, optional): Include full metadata (default: true)
  • version (integer, optional): Specific version number

Returns:

  • 200 OK: Item object
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Access denied
  • 404 Not Found: Item or version not found

PUT /api/v1/items/{item_id}

Update item metadata.

Arguments:

  • item_id (string, required): Item UUID
  • title (string, optional): Updated title
  • description (string, optional): Updated description
  • metadata (object, optional): Updated metadata fields
  • visibility (enum, optional): Updated visibility
  • create_version (boolean, optional): Create new version (default: false)

Returns:

  • 200 OK: Updated item object
  • 400 Bad Request: Invalid input data
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Item not found
  • 422 Unprocessable Entity: Metadata validation failed

DELETE /api/v1/items/{item_id}

Delete or withdraw an item.

Arguments:

  • item_id (string, required): Item UUID
  • permanent (boolean, optional): Permanent deletion vs withdrawal (default: false)
  • reason (string, optional): Withdrawal/deletion reason

Returns:

  • 204 No Content: Item deleted/withdrawn
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Item not found
  • 409 Conflict: Item has active preservation processes

GET /api/v1/items

Search and list items.

Arguments:

  • query (string, optional): Full-text search query
  • collection_id (string, optional): Filter by collection
  • item_type (string, optional): Filter by type
  • visibility (enum, optional): Filter by visibility
  • metadata_filters (object, optional): Filter by metadata fields
  • from_date (datetime, optional): Filter by creation date
  • to_date (datetime, optional): Filter by creation date
  • facets (array, optional): Requested facet fields
  • sort (enum, optional): Sort field
  • order (enum, optional): asc, desc
  • page (integer, optional): Page number
  • per_page (integer, optional): Items per page (max: 100)

Returns:

  • 200 OK: Search results with items array, facets, and pagination
  • 400 Bad Request: Invalid query syntax
  • 401 Unauthorized: Authentication required

3. File/Bitstream Management

Purpose: Handle upload, storage, retrieval, and versioning of files (bitstreams) associated with repository items. Supports multiple file formats and preservation formats.

Endpoints

POST /api/v1/items/{item_id}/files

Upload a file to an item.

Arguments:

  • item_id (string, required): Item UUID
  • file (binary, required): File content (multipart upload)
  • filename (string, required): Original filename
  • bundle (enum, required): ORIGINAL, DERIVATIVE, THUMBNAIL, METADATA, TEXT
  • mime_type (string, optional): MIME type (auto-detected if not provided)
  • description (string, optional): File description
  • checksum (string, optional): Pre-calculated checksum for verification
  • checksum_algorithm (enum, optional): MD5, SHA256, SHA512

Returns:

  • 201 Created: File object with UUID and download URL
  • 400 Bad Request: Invalid file or parameters
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Item not found
  • 409 Conflict: File with same name exists
  • 413 Payload Too Large: File exceeds size limit
  • 415 Unsupported Media Type: File type not allowed
  • 422 Unprocessable Entity: Checksum verification failed

GET /api/v1/items/{item_id}/files

List files for an item.

Arguments:

  • item_id (string, required): Item UUID
  • bundle (enum, optional): Filter by bundle type
  • version (integer, optional): Specific item version

Returns:

  • 200 OK: Array of file objects
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Access denied
  • 404 Not Found: Item not found

GET /api/v1/files/{file_id}

Download a file.

Arguments:

  • file_id (string, required): File UUID
  • disposition (enum, optional): inline, attachment (default: inline)

Returns:

  • 200 OK: File content with appropriate headers
  • 302 Found: Redirect to CDN/storage URL
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Access denied
  • 404 Not Found: File not found
  • 410 Gone: File deleted or permanently unavailable

PUT /api/v1/files/{file_id}

Update file metadata.

Arguments:

  • file_id (string, required): File UUID
  • filename (string, optional): Updated filename
  • description (string, optional): Updated description
  • bundle (enum, optional): Updated bundle type

Returns:

  • 200 OK: Updated file object
  • 400 Bad Request: Invalid input
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: File not found

DELETE /api/v1/files/{file_id}

Delete a file.

Arguments:

  • file_id (string, required): File UUID
  • reason (string, optional): Deletion reason

Returns:

  • 204 No Content: File deleted
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: File not found
  • 409 Conflict: File is only preservation copy

POST /api/v1/files/{file_id}/derivatives

Generate derivative files.

Arguments:

  • file_id (string, required): Source file UUID
  • format (enum, required): Target format (e.g., PDF, JPEG, PNG, WEBP)
  • options (object, optional): Format-specific options (resolution, quality, etc.)

Returns:

  • 201 Created: Derivative file object
  • 202 Accepted: Derivative generation queued
  • 400 Bad Request: Invalid format or options
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: File not found
  • 415 Unsupported Media Type: Conversion not supported

4. Metadata Management

Purpose: Define, validate, and manage metadata schemas and vocabularies. Supports multiple metadata standards (Dublin Core, MODS, PREMIS, etc.) and custom schemas.

Endpoints

GET /api/v1/metadata/schemas

List available metadata schemas.

Arguments:

  • type (string, optional): Filter by schema type
  • active (boolean, optional): Filter active schemas

Returns:

  • 200 OK: Array of schema objects
  • 401 Unauthorized: Authentication required

GET /api/v1/metadata/schemas/{schema_id}

Retrieve a metadata schema.

Arguments:

  • schema_id (string, required): Schema UUID or identifier
  • version (string, optional): Schema version

Returns:

  • 200 OK: Schema definition (JSON Schema format)
  • 404 Not Found: Schema not found

POST /api/v1/metadata/schemas

Create a custom metadata schema.

Arguments:

  • name (string, required): Schema name
  • description (string, optional): Schema description
  • version (string, required): Schema version
  • schema (object, required): JSON Schema definition
  • namespace (string, optional): XML namespace for export

Returns:

  • 201 Created: Schema object
  • 400 Bad Request: Invalid schema definition
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions
  • 409 Conflict: Schema already exists

POST /api/v1/metadata/validate

Validate metadata against a schema.

Arguments:

  • schema_id (string, required): Schema UUID
  • metadata (object, required): Metadata to validate

Returns:

  • 200 OK: Validation result with errors/warnings
  • 400 Bad Request: Invalid request
  • 404 Not Found: Schema not found

GET /api/v1/metadata/vocabularies

List controlled vocabularies.

Arguments:

  • type (string, optional): Vocabulary type
  • language (string, optional): Language code

Returns:

  • 200 OK: Array of vocabulary objects
  • 401 Unauthorized: Authentication required

GET /api/v1/metadata/vocabularies/{vocab_id}/terms

Search vocabulary terms.

Arguments:

  • vocab_id (string, required): Vocabulary UUID
  • query (string, optional): Search query
  • parent_term (string, optional): Filter by parent term
  • page (integer, optional): Page number
  • per_page (integer, optional): Terms per page

Returns:

  • 200 OK: Array of term objects
  • 404 Not Found: Vocabulary not found

5. Access Control & Permissions

Purpose: Manage user authentication, authorization, access policies, and embargo management. Supports role-based access control (RBAC) and fine-grained permissions.

Endpoints

POST /api/v1/auth/login

Authenticate a user.

Arguments:

  • username (string, required): Username or email
  • password (string, required): Password
  • mfa_code (string, optional): Multi-factor authentication code

Returns:

  • 200 OK: Authentication token and user object
  • 400 Bad Request: Missing credentials
  • 401 Unauthorized: Invalid credentials
  • 403 Forbidden: Account locked or disabled
  • 428 Precondition Required: MFA code required

POST /api/v1/auth/logout

Invalidate authentication token.

Arguments:

  • None (uses Authorization header)

Returns:

  • 204 No Content: Successfully logged out
  • 401 Unauthorized: Invalid or expired token

POST /api/v1/auth/refresh

Refresh authentication token.

Arguments:

  • refresh_token (string, required): Refresh token

Returns:

  • 200 OK: New authentication token
  • 401 Unauthorized: Invalid refresh token

GET /api/v1/users/{user_id}/permissions

Get user permissions.

Arguments:

  • user_id (string, required): User UUID
  • resource_type (enum, optional): Filter by resource type
  • resource_id (string, optional): Specific resource UUID

Returns:

  • 200 OK: Array of permission objects
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Cannot view other user's permissions
  • 404 Not Found: User not found

POST /api/v1/access-policies

Create an access policy.

Arguments:

  • name (string, required): Policy name
  • description (string, optional): Policy description
  • rules (array, required): Array of access rules
  • default_action (enum, required): allow, deny

Returns:

  • 201 Created: Access policy object
  • 400 Bad Request: Invalid policy definition
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions

GET /api/v1/access-policies/{policy_id}

Retrieve an access policy.

Arguments:

  • policy_id (string, required): Policy UUID

Returns:

  • 200 OK: Access policy object
  • 401 Unauthorized: Authentication required
  • 404 Not Found: Policy not found

PUT /api/v1/access-policies/{policy_id}

Update an access policy.

Arguments:

  • policy_id (string, required): Policy UUID
  • name (string, optional): Updated name
  • description (string, optional): Updated description
  • rules (array, optional): Updated rules

Returns:

  • 200 OK: Updated policy object
  • 400 Bad Request: Invalid policy definition
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Policy not found

DELETE /api/v1/access-policies/{policy_id}

Delete an access policy.

Arguments:

  • policy_id (string, required): Policy UUID
  • replacement_policy_id (string, optional): Replacement policy for affected resources

Returns:

  • 204 No Content: Policy deleted
  • 400 Bad Request: Policy in use without replacement
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Policy not found

POST /api/v1/items/{item_id}/embargoes

Set embargo on an item.

Arguments:

  • item_id (string, required): Item UUID
  • embargo_date (datetime, required): Embargo lift date
  • embargo_type (enum, required): metadata, files, full
  • reason (string, optional): Embargo reason

Returns:

  • 201 Created: Embargo object
  • 400 Bad Request: Invalid embargo date or type
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Item not found

DELETE /api/v1/items/{item_id}/embargoes/{embargo_id}

Lift embargo.

Arguments:

  • item_id (string, required): Item UUID
  • embargo_id (string, required): Embargo UUID

Returns:

  • 204 No Content: Embargo lifted
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Item or embargo not found

6. Preservation

Purpose: Digital preservation actions including fixity checking, format validation, migration, and audit trail management. Ensures long-term accessibility and authenticity of digital objects.

Endpoints

POST /api/v1/preservation/fixity-checks

Schedule fixity check.

Arguments:

  • resource_type (enum, required): item, file, collection
  • resource_id (string, required): Resource UUID
  • algorithm (enum, optional): MD5, SHA256, SHA512 (default: SHA256)
  • recursive (boolean, optional): Check all child resources (default: false)

Returns:

  • 202 Accepted: Fixity check scheduled with job ID
  • 400 Bad Request: Invalid parameters
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Resource not found

GET /api/v1/preservation/fixity-checks/{job_id}

Get fixity check status.

Arguments:

  • job_id (string, required): Job UUID

Returns:

  • 200 OK: Fixity check result object
  • 202 Accepted: Check still in progress
  • 401 Unauthorized: Authentication required
  • 404 Not Found: Job not found

GET /api/v1/preservation/fixity-checks

List fixity check history.

Arguments:

  • resource_type (enum, optional): Filter by resource type
  • resource_id (string, optional): Filter by resource
  • status (enum, optional): pending, running, success, failed
  • from_date (datetime, optional): Filter by date range
  • to_date (datetime, optional): Filter by date range
  • page (integer, optional): Page number
  • per_page (integer, optional): Results per page

Returns:

  • 200 OK: Array of fixity check objects with pagination
  • 401 Unauthorized: Authentication required

POST /api/v1/preservation/format-validation

Validate file format.

Arguments:

  • file_id (string, required): File UUID
  • validation_profile (string, optional): Specific validation profile

Returns:

  • 200 OK: Validation result with format identification and conformance
  • 202 Accepted: Validation queued
  • 400 Bad Request: Invalid parameters
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: File not found

POST /api/v1/preservation/migrations

Schedule format migration.

Arguments:

  • file_id (string, required): Source file UUID
  • target_format (string, required): Target format identifier
  • migration_strategy (enum, required): replace, derivative, version
  • validation_required (boolean, optional): Validate before/after (default: true)
  • options (object, optional): Migration tool options

Returns:

  • 202 Accepted: Migration job created
  • 400 Bad Request: Invalid migration parameters
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: File not found
  • 415 Unsupported Media Type: Migration not supported

GET /api/v1/preservation/migrations/{job_id}

Get migration job status.

Arguments:

  • job_id (string, required): Migration job UUID

Returns:

  • 200 OK: Migration job status and results
  • 202 Accepted: Migration in progress
  • 401 Unauthorized: Authentication required
  • 404 Not Found: Job not found

GET /api/v1/preservation/audit-log

Query preservation audit log.

Arguments:

  • resource_type (enum, optional): Filter by resource type
  • resource_id (string, optional): Filter by resource
  • event_type (enum, optional): Filter by event type
  • user_id (string, optional): Filter by user
  • from_date (datetime, required): Start of date range
  • to_date (datetime, required): End of date range
  • page (integer, optional): Page number
  • per_page (integer, optional): Results per page

Returns:

  • 200 OK: Array of audit log entries with pagination
  • 400 Bad Request: Invalid query parameters
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions

GET /api/v1/preservation/formats

List supported preservation formats.

Arguments:

  • category (string, optional): Format category (image, document, video, etc.)
  • migration_source (boolean, optional): Formats that can be migrated from
  • migration_target (boolean, optional): Formats that can be migrated to

Returns:

  • 200 OK: Array of format objects with metadata
  • 401 Unauthorized: Authentication required

7. Batch Operations

Purpose: Perform bulk operations on multiple items, files, or collections. Supports asynchronous processing with progress tracking and error reporting.

Endpoints

POST /api/v1/batch/import

Batch import items.

Arguments:

  • source_type (enum, required): csv, zip, bag, mets
  • collection_id (string, required): Target collection UUID
  • source_url (string, optional): URL to import source
  • source_file (binary, optional): Upload import file
  • mapping (object, optional): Metadata field mapping
  • options (object, optional): Import options
  • validate_only (boolean, optional): Dry run (default: false)

Returns:

  • 202 Accepted: Import job created with job ID
  • 400 Bad Request: Invalid import configuration
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Collection not found
  • 413 Payload Too Large: Import file too large

GET /api/v1/batch/jobs/{job_id}

Get batch job status.

Arguments:

  • job_id (string, required): Job UUID

Returns:

  • 200 OK: Job status with progress and results
  • 401 Unauthorized: Authentication required
  • 404 Not Found: Job not found

DELETE /api/v1/batch/jobs/{job_id}

Cancel a batch job.

Arguments:

  • job_id (string, required): Job UUID

Returns:

  • 204 No Content: Job cancelled
  • 400 Bad Request: Job cannot be cancelled
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Job not found

POST /api/v1/batch/update

Batch update metadata.

Arguments:

  • item_ids (array, required): Array of item UUIDs
  • metadata_updates (object, required): Metadata fields to update
  • update_strategy (enum, required): merge, replace, append

Returns:

  • 202 Accepted: Update job created
  • 400 Bad Request: Invalid update configuration
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions

POST /api/v1/batch/delete

Batch delete items.

Arguments:

  • item_ids (array, required): Array of item UUIDs
  • permanent (boolean, optional): Permanent deletion (default: false)
  • reason (string, optional): Deletion reason

Returns:

  • 202 Accepted: Deletion job created
  • 400 Bad Request: Invalid parameters
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions

POST /api/v1/batch/export

Batch export items.

Arguments:

  • item_ids (array, optional): Specific items to export
  • collection_id (string, optional): Export entire collection
  • format (enum, required): csv, json, mets, bag
  • include_files (boolean, optional): Include bitstreams (default: false)
  • metadata_format (string, optional): Metadata export format

Returns:

  • 202 Accepted: Export job created
  • 400 Bad Request: Invalid export configuration
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions

GET /api/v1/batch/jobs

List batch jobs.

Arguments:

  • status (enum, optional): Filter by status
  • job_type (enum, optional): Filter by job type
  • user_id (string, optional): Filter by user
  • from_date (datetime, optional): Filter by creation date
  • to_date (datetime, optional): Filter by creation date
  • page (integer, optional): Page number
  • per_page (integer, optional): Jobs per page

Returns:

  • 200 OK: Array of job objects with pagination
  • 401 Unauthorized: Authentication required

8. Statistics & Analytics

Purpose: Provide usage statistics, analytics, and reporting for items, collections, and overall repository activity. Supports customizable dashboards and data export.

Endpoints

GET /api/v1/statistics/items/{item_id}

Get item statistics.

Arguments:

  • item_id (string, required): Item UUID
  • from_date (datetime, optional): Start date for metrics
  • to_date (datetime, optional): End date for metrics
  • metrics (array, optional): Specific metrics to retrieve

Returns:

  • 200 OK: Item statistics object (views, downloads, citations, etc.)
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Access denied
  • 404 Not Found: Item not found

GET /api/v1/statistics/collections/{collection_id}

Get collection statistics.

Arguments:

  • collection_id (string, required): Collection UUID
  • from_date (datetime, optional): Start date
  • to_date (datetime, optional): End date
  • include_subcollections (boolean, optional): Include child collections (default: true)

Returns:

  • 200 OK: Collection statistics object
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Access denied
  • 404 Not Found: Collection not found

GET /api/v1/statistics/repository

Get repository-wide statistics.

Arguments:

  • from_date (datetime, optional): Start date
  • to_date (datetime, optional): End date
  • breakdown_by (enum, optional): collection, item_type, user, date

Returns:

  • 200 OK: Repository statistics object
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions

GET /api/v1/statistics/downloads

Download statistics query.

Arguments:

  • resource_type (enum, optional): item, file, collection
  • resource_id (string, optional): Specific resource UUID
  • from_date (datetime, optional): Start date
  • to_date (datetime, optional): End date
  • group_by (enum, optional): day, week, month, year
  • country (string, optional): Filter by country code
  • page (integer, optional): Page number
  • per_page (integer, optional): Results per page

Returns:

  • 200 OK: Download statistics with pagination
  • 400 Bad Request: Invalid query parameters
  • 401 Unauthorized: Authentication required

GET /api/v1/statistics/top-items

Get most accessed items.

Arguments:

  • metric (enum, required): views, downloads, citations
  • from_date (datetime, optional): Start date
  • to_date (datetime, optional): End date
  • collection_id (string, optional): Filter by collection
  • limit (integer, optional): Number of results (max: 100)

Returns:

  • 200 OK: Array of items with statistics
  • 400 Bad Request: Invalid parameters
  • 401 Unauthorized: Authentication required

POST /api/v1/statistics/reports

Generate custom report.

Arguments:

  • report_type (string, required): Report type identifier
  • parameters (object, required): Report parameters
  • format (enum, required): json, csv, pdf, xlsx
  • delivery_method (enum, optional): download, email (default: download)

Returns:

  • 202 Accepted: Report generation started
  • 400 Bad Request: Invalid report configuration
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions

GET /api/v1/statistics/reports/{report_id}

Get generated report.

Arguments:

  • report_id (string, required): Report UUID

Returns:

  • 200 OK: Report file or download URL
  • 202 Accepted: Report still generating
  • 401 Unauthorized: Authentication required
  • 404 Not Found: Report not found
  • 410 Gone: Report expired

9. Workflow & Review

Purpose: Manage submission workflows, peer review processes, and approval chains. Supports configurable multi-step workflows with notifications and delegation.

Endpoints

GET /api/v1/workflows

List available workflows.

Arguments:

  • active (boolean, optional): Filter active workflows
  • type (string, optional): Filter by workflow type

Returns:

  • 200 OK: Array of workflow definitions
  • 401 Unauthorized: Authentication required

GET /api/v1/workflows/{workflow_id}

Get workflow definition.

Arguments:

  • workflow_id (string, required): Workflow UUID

Returns:

  • 200 OK: Workflow definition object
  • 401 Unauthorized: Authentication required
  • 404 Not Found: Workflow not found

POST /api/v1/workflow-items

Start a workflow for an item.

Arguments:

  • workflow_id (string, required): Workflow UUID
  • item_id (string, optional): Existing item UUID
  • collection_id (string, required): Target collection
  • initial_data (object, optional): Initial workflow data

Returns:

  • 201 Created: Workflow item object
  • 400 Bad Request: Invalid workflow configuration
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Workflow or collection not found

GET /api/v1/workflow-items/{workflow_item_id}

Get workflow item status.

Arguments:

  • workflow_item_id (string, required): Workflow item UUID

Returns:

  • 200 OK: Workflow item with current state and history
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Access denied
  • 404 Not Found: Workflow item not found

POST /api/v1/workflow-items/{workflow_item_id}/actions

Perform workflow action.

Arguments:

  • workflow_item_id (string, required): Workflow item UUID
  • action (enum, required): approve, reject, request_changes, claim, unclaim
  • comment (string, optional): Action comment
  • data (object, optional): Action-specific data

Returns:

  • 200 OK: Updated workflow item
  • 400 Bad Request: Invalid action or data
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Action not allowed in current state
  • 404 Not Found: Workflow item not found
  • 409 Conflict: Workflow item in wrong state for action

GET /api/v1/workflow-items

List workflow items.

Arguments:

  • workflow_id (string, optional): Filter by workflow
  • state (string, optional): Filter by current state
  • assigned_to (string, optional): Filter by assigned user
  • submitter (string, optional): Filter by submitter
  • collection_id (string, optional): Filter by collection
  • page (integer, optional): Page number
  • per_page (integer, optional): Items per page

Returns:

  • 200 OK: Array of workflow items with pagination
  • 401 Unauthorized: Authentication required

GET /api/v1/workflow-items/{workflow_item_id}/history

Get workflow history.

Arguments:

  • workflow_item_id (string, required): Workflow item UUID

Returns:

  • 200 OK: Array of workflow actions and state changes
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Access denied
  • 404 Not Found: Workflow item not found

10. Integration & Export

Purpose: Enable integration with external systems through standard protocols (OAI-PMH, SWORD, IIIF) and custom webhooks. Support data export in various formats.

Endpoints

GET /api/v1/oai

OAI-PMH endpoint.

Arguments:

  • verb (enum, required): OAI-PMH verb (Identify, ListMetadataFormats, ListSets, ListIdentifiers, ListRecords, GetRecord)
  • metadataPrefix (string, conditional): Metadata format
  • identifier (string, conditional): Item identifier
  • from (datetime, optional): Selective harvesting start date
  • until (datetime, optional): Selective harvesting end date
  • set (string, optional): Set specification
  • resumptionToken (string, optional): Resumption token for pagination

Returns:

  • 200 OK: OAI-PMH XML response
  • 400 Bad Request: Bad argument
  • 404 Not Found: ID does not exist
  • 422 Unprocessable Entity: Cannot disseminate format

POST /api/v1/sword/collections/{collection_id}

SWORD deposit endpoint.

Arguments:

  • collection_id (string, required): Target collection UUID
  • Content in request body (ZIP, METS, etc.)
  • Headers: Content-Type, Content-Disposition, Content-MD5

Returns:

  • 201 Created: Deposit receipt
  • 400 Bad Request: Invalid deposit
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Collection not found
  • 415 Unsupported Media Type: Format not accepted

GET /api/v1/iiif/items/{item_id}/manifest

IIIF Presentation API manifest.

Arguments:

  • item_id (string, required): Item UUID

Returns:

  • 200 OK: IIIF manifest JSON
  • 404 Not Found: Item not found or no suitable images

GET /api/v1/iiif/2/{item_id}/{file_id}/{region}/{size}/{rotation}/{quality}.{format}

IIIF Image API endpoint.

Arguments:

  • item_id (string, required): Item UUID
  • file_id (string, required): File UUID
  • region (string, required): Image region
  • size (string, required): Image size
  • rotation (string, required): Rotation
  • quality (string, required): Quality
  • format (string, required): Output format

Returns:

  • 200 OK: Image data
  • 400 Bad Request: Invalid IIIF parameters
  • 404 Not Found: Item or file not found

POST /api/v1/webhooks

Register a webhook.

Arguments:

  • url (string, required): Webhook endpoint URL
  • events (array, required): Array of event types to subscribe to
  • secret (string, optional): Webhook signing secret
  • active (boolean, optional): Webhook active status (default: true)

Returns:

  • 201 Created: Webhook registration object with UUID
  • 400 Bad Request: Invalid webhook configuration
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions

GET /api/v1/webhooks

List registered webhooks.

Arguments:

  • active (boolean, optional): Filter by active status

Returns:

  • 200 OK: Array of webhook objects
  • 401 Unauthorized: Authentication required

DELETE /api/v1/webhooks/{webhook_id}

Delete a webhook.

Arguments:

  • webhook_id (string, required): Webhook UUID

Returns:

  • 204 No Content: Webhook deleted
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Webhook not found

GET /api/v1/export/formats

List available export formats.

Arguments:

  • resource_type (enum, optional): item, collection, metadata

Returns:

  • 200 OK: Array of supported export format objects
  • 401 Unauthorized: Authentication required

POST /api/v1/export

Export resources.

Arguments:

  • resource_type (enum, required): item, collection
  • resource_ids (array, required): Array of resource UUIDs
  • format (enum, required): Export format
  • options (object, optional): Format-specific options
  • include_files (boolean, optional): Include bitstreams (default: false)

Returns:

  • 202 Accepted: Export job created
  • 400 Bad Request: Invalid export configuration
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions

11. System Administration

Purpose: System configuration, user management, monitoring, and maintenance operations. Restricted to administrative users.

Endpoints

GET /api/v1/admin/system/health

System health check.

Arguments:

  • detailed (boolean, optional): Include component details (default: false)

Returns:

  • 200 OK: Health status object
  • 503 Service Unavailable: System unhealthy
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions

GET /api/v1/admin/system/info

Get system information.

Arguments: None

Returns:

  • 200 OK: System version, configuration, and capacity info
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions

GET /api/v1/admin/users

List users.

Arguments:

  • query (string, optional): Search query
  • role (string, optional): Filter by role
  • status (enum, optional): active, inactive, locked
  • page (integer, optional): Page number
  • per_page (integer, optional): Users per page

Returns:

  • 200 OK: Array of user objects with pagination
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions

POST /api/v1/admin/users

Create a user.

Arguments:

  • username (string, required): Username
  • email (string, required): Email address
  • password (string, required): Initial password
  • first_name (string, required): First name
  • last_name (string, required): Last name
  • roles (array, optional): Array of role identifiers

Returns:

  • 201 Created: User object
  • 400 Bad Request: Invalid user data
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions
  • 409 Conflict: Username or email already exists

PUT /api/v1/admin/users/{user_id}

Update user.

Arguments:

  • user_id (string, required): User UUID
  • email (string, optional): Updated email
  • first_name (string, optional): Updated first name
  • last_name (string, optional): Updated last name
  • roles (array, optional): Updated roles
  • status (enum, optional): Updated status

Returns:

  • 200 OK: Updated user object
  • 400 Bad Request: Invalid update data
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: User not found

DELETE /api/v1/admin/users/{user_id}

Delete or deactivate user.

Arguments:

  • user_id (string, required): User UUID
  • permanent (boolean, optional): Permanent deletion (default: false)

Returns:

  • 204 No Content: User deleted/deactivated
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: User not found
  • 409 Conflict: User owns resources

GET /api/v1/admin/audit-log

Query system audit log.

Arguments:

  • user_id (string, optional): Filter by user
  • action (string, optional): Filter by action type
  • resource_type (enum, optional): Filter by resource type
  • resource_id (string, optional): Filter by resource
  • from_date (datetime, required): Start date
  • to_date (datetime, required): End date
  • page (integer, optional): Page number
  • per_page (integer, optional): Entries per page

Returns:

  • 200 OK: Array of audit log entries with pagination
  • 400 Bad Request: Invalid query parameters
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions

POST /api/v1/admin/maintenance/reindex

Trigger search index rebuild.

Arguments:

  • resource_type (enum, optional): item, collection, all
  • resource_id (string, optional): Specific resource UUID

Returns:

  • 202 Accepted: Reindex job started
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions

POST /api/v1/admin/maintenance/cache-clear

Clear application caches.

Arguments:

  • cache_type (enum, optional): Specific cache to clear

Returns:

  • 204 No Content: Cache cleared
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions

GET /api/v1/admin/storage/usage

Get storage usage statistics.

Arguments:

  • breakdown_by (enum, optional): collection, item_type, file_type

Returns:

  • 200 OK: Storage usage statistics
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions

Common Response Codes

All endpoints may return the following error codes:

  • 500 Internal Server Error: Unexpected server error
  • 502 Bad Gateway: Upstream service failure
  • 503 Service Unavailable: Service temporarily unavailable
  • 504 Gateway Timeout: Request timeout

Common Headers

Request Headers

  • Authorization: Bearer token for authentication
  • Content-Type: Request content type
  • Accept: Desired response content type
  • X-API-Version: API version (optional, defaults to latest)

Response Headers

  • Content-Type: Response content type
  • X-Rate-Limit-Limit: Rate limit maximum
  • X-Rate-Limit-Remaining: Remaining requests
  • X-Rate-Limit-Reset: Rate limit reset time
  • X-Request-ID: Unique request identifier for debugging

Pagination

List endpoints support pagination with the following query parameters:

  • page: Page number (1-based)
  • per_page: Items per page (default: 20, max: 100)

Pagination metadata is included in responses:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total_pages": 10,
    "total_count": 200
  }
}

Versioning

The API uses URL-based versioning (/api/v1/). Clients should specify the API version in the URL. Deprecated endpoints will be supported for at least one major version cycle.

Rate Limiting

  • Default: 1000 requests per hour per authenticated user
  • Anonymous: 100 requests per hour per IP address
  • Rate limits may vary by endpoint and user role

Error Response Format

All error responses follow a consistent format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      "field": "Specific field error information"
    },
    "request_id": "unique-request-id"
  }
}

Document Version: 1.0.0
Last Updated: 2026-02-26
Contact: Digital Repository Team

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment