Using the single-collection importer

KCWorks provides a standalone Python package that simplifies the process of importing works via the import API. The package (kcworks-import-client, module kcworks_import_client) handles authentication, file uploads, multipart form data encoding, and provides human-readable success and error messages.

Requirements

The client requires Python 3.12 or later and the requests library. Install from this package directory:

pip install -e .
# or with uv:
uv pip install -e .

This installs the kcworks-api-importer and kcworks-multi-collection-importer console commands.

Library API

Applications can import service classes instead of shelling out to the CLI:

from kcworks_import_client import ImportClient, MultiCollectionImporter

client = ImportClient(api_key="...")
result = client.import_works(
    "my-collection",
    metadata=[{"metadata": {"title": "Example"}}],  # path, JSON str, list, or dict
    files=["paper.pdf"],  # paths or (filename, fileobj[, mime]) tuples
)
# result.ok, result.status_code, result.data, result.errors

importer = MultiCollectionImporter(api_key="...")
multi = importer.run_manifest("manifest.json", assign_parents=True)

ImportResult / MultiCollectionImportResult are returned for HTTP outcomes; transport failures raise ImportRequestError. Prefer these classes over the CLI-oriented import_works(...) helper (which prints status and returns an exit code).

Command-Line Arguments

The script accepts the following command-line arguments:

Argument

Description

--api-key KEY

API key for authentication. If not provided, checks KCWORKS_IMPORT_API_KEY environment variable, or prompts interactively.

--collection-id ID

Collection ID or slug to import records into. If not provided, checks KCWORKS_IMPORT_COLLECTION_ID environment variable, or prompts interactively.

--metadata PATH

Path to the metadata JSON file. The metadata must be a JSON array of metadata objects, even if importing a single record. If not provided, checks KCWORKS_IMPORT_METADATA_PATH environment variable, or prompts interactively.

--files PATH [PATH ...]

One or more file paths to upload with the records. Multiple files can be specified by providing multiple arguments. If not provided, checks KCWORKS_IMPORT_FILES_PATH environment variable (comma or space-separated), or prompts interactively.

--output PATH

Optional folder for the timestamped response JSON report. If not provided, checks KCWORKS_IMPORT_OUTPUT_PATH, or prompts interactively (Enter → current working directory). Ignored with --suppress-reports.

--skip-output-prompt

Skip the output-folder prompt and use the current working directory when --output / env are unset.

--testing

Use a local testing instance (https://localhost).

--notify-record-owners

Send email notifications to users listed as record owners in metadata. Default: off.

--id-scheme SCHEME

Identifier scheme for import deduplication (default: import-recid). Must be defined in KCWorks or pre-arranged for addition.

--alternate-id-scheme

Optional secondary identifier scheme for deduplication. Same constraint as --id-scheme.

--no-updates

Refuse to change an existing matched record when metadata differs (skips file reconciliation in that case). Default: allow metadata updates; files then follow the key/size rules under Files when re-importing an existing work (no_updates is "false").

Environment Variables

All command-line arguments can also be provided via environment variables:

  • KCWORKS_IMPORT_API_KEY - API key for authentication

  • KCWORKS_IMPORT_COLLECTION_ID - Collection ID or slug

  • KCWORKS_IMPORT_METADATA_PATH - Path to metadata JSON file

  • KCWORKS_IMPORT_FILES_PATH - File paths, comma or space-separated

  • KCWORKS_IMPORT_OUTPUT_PATH - Path to save response JSON

Usage Examples

Basic usage with all arguments:

kcworks-api-importer \
  --api-key "your-api-key" \
  --collection-id "my-collection" \
  --metadata "metadata.json" \
  --files "file1.pdf" "file2.docx" \
  --output "response.json"

Using environment variables:

export KCWORKS_IMPORT_API_KEY="your-api-key"
export KCWORKS_IMPORT_COLLECTION_ID="my-collection"
export KCWORKS_IMPORT_METADATA_PATH="metadata.json"
export KCWORKS_IMPORT_FILES_PATH="file1.pdf file2.docx"
python -m kcworks_import_client.api_importer --output "response.json"

Interactive mode (will prompt for missing values):

python -m kcworks_import_client.api_importer

Single file upload:

python -m kcworks_import_client.api_importer \
  --api-key "your-api-key" \
  --collection-id "my-collection" \
  --metadata "metadata.json" \
  --files "document.pdf"

Response Handling

The script provides human-readable output for both successful and failed imports:

  • Success (201): Shows checkmark, number of records imported, record IDs, and URLs

  • Partial success (207): Shows warning, lists successful and failed records with error details

  • Failure (400, 403, 500): Shows error message, explains the issue, and lists failed records with specific errors

If an output path is provided, the full API response is also saved to that file as formatted JSON (or plain text if the response is not JSON).

Exit Codes

  • 0 - Success

  • 1 - Error (invalid input, file not found, API error, etc.)