Archivematica API

Main Page > Development > Archivematica API

Endpoints require authentication with a username and API key. This can be submitted as GET parameters (eg ?username=demo&api_key=e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2) or as a header (eg Authorization: ApiKey demo:e6282adabed84e39ffe451f8bf6ff1a67c1fc9f2)

Endpoints return JSON. If there's an error, they will return a 4xx or 5xx HTTP error code and a JSON body {'error': True, 'message': 'message describing error'}

Transfer

Start Transfer

• URL: /api/transfer/start_transfer/
• Verb: POST
• Start a transfer.
• Parameters: JSON body
  • name: Name of new transfer
  • type: Type of the new transfer. One of: standard, unzipped bag, zipped bag, dspace
  • accession: Accession number of new transfer
  • paths[]: List of base64-encoded "<location_uuid>:<relative_path>" to be copied into the new transfer. Location UUIDs should be associated with this pipeline, and relative path should be relative to the location (TODO confirm relative vs absolute path). E.g. NWJiYWJjMTMtMTIyNy00MWE3LWIwY2QtZjJhYzM1MjkxZTdmOi92YWdyYW50L3NhbXBsZWRhdGEvQ1NWbWV0YWRhdGE= (decoded: 5bbabc13-1227-41a7-b0cd-f2ac35291e7f:/vagrant/sampledata/CSVmetadata)
  • row_ids[]: ID of the associated TransferMetadataSet for disk image ingest. Can be provided as [""]
• Response: JSON
  • message: "Copy successful."
  • path: Path the transfer was copied to on start?

List Unapproved Transfers

• URL: /api/transfer/unapproved
• Verb: GET
• Returns a list of transfers waiting for approval.
• Response: JSON
  • message: "Fetched unapproved transfers successfully."
  • results: List of dicts with keys:
    • type: Transfer type. One of: standard, unzipped bag, zipped bag, dspace
    • directory: Directory the transfer is in currently
    • uuid: UUID of the transfer

Approve Transfer

• URL: /api/transfer/approve
• Verb: POST
• Approve a transfer waiting to be started.
• Parameters: JSON body
  • type: Type of the transfer to approved. One of: standard, unzipped bag, zipped bag, dspace.
  • directory: Name of the directory for the transfer to approve
• Response: JSON
  • message: "Approval successful."
  • uuid: UUID of the approved transfer

Status

• URL: /transfer/status/<transfer UUID>/
• Verb: GET
• Returns the status of the transfer.
• Response: JSON
  • status: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING
  • name: Name of the transfer, e.g. "imgs"
  • sip_uuid: If status is COMPLETE, this field will exist with either the UUID of the SIP or 'BACKLOG'
  • microservice: Name of the current microservice
  • directory: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"
  • path: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/watchedDirectories/SIPCreation/completedTransfers/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"
  • message: "Fetched status for <transfer UUID> successfully."
  • type: "transfer"
  • uuid: UUID of the transfer, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"

Hide

• URL: /api/transfer/<transfer UUID>/delete/
• Verb: DELETE
• Hide a transfer
• Response: JSON
  • removed: True

Completed

• URL: /api/transfer/completed/
• Verb: GET
• Return list of Transfers that are completed
• Response: JSON
  • message: "Fetched completed transfers successfully."
  • results: List of UUIDs of completed Transfers
• Added in Archivematica 1.6

Start Reingest

• URL: /api/transfer/reingest
• Verb: POST
• Start a full reingest.
• Parameters: JSON body
  • name: Name of the AIP. The AIP should also be found at %sharedDirectory%/tmp/<name>
  • uuid: UUID of the AIP to reingest
• Response: JSON
  • message: "Approval successful."
  • reingest_uuid: UUID of the reingested transfer

Ingest

Status

• URL: /ingest/status/<unit UUID>/
• Verb: GET
• Returns the status of the SIP
• Response: JSON
  • status: One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING
  • name: Name of the SIP, e.g. "imgs"
  • microservice: Name of the current microservice
  • directory: Name of the directory, e.g. "imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c"
  • path: Full path to the transfer, e.g. "/var/archivematica/sharedDirectory/currentlyProcessing/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c/"
  • message: "Fetched status for <SIP UUID> successfully."
  • type: "SIP"
  • uuid: UUID of the SIP, e.g. "52dd0c01-e803-423a-be5f-b592b5d5d61c"

Hide

• URL: /api/ingest/<SIP UUID>/delete/
• Verb: DELETE
• Hide a SIP
• Response: JSON
  • removed: True

List SIPS Waiting for User Input

• URL: /api/ingest/waiting
• Verb: GET
• Returns a list of SIPs waiting for user input.
• Response: JSON
  • message: "Fetched units successfully."
  • results: List of dicts with keys:
    • sip_directory: Directory the SIP is in currently
    • sip_uuid: UUID of the SIP
    • sip_name: Name of the SIP
    • microservice: Name of the current microservice

Improvement Note: Despite the URL, this currently returns both SIPs & transfers that are waiting for user input. A separate /api/transfer/waiting should be added for transfers.

Completed

• URL: /api/ingest/completed/
• Verb: GET
• Return list of SIPs that are completed
• Response: JSON
  • message: "Fetched completed ingests successfully."
  • results: List of UUIDs of completed SIPs
• Added in Archivematica 1.6

Reingest

• URL: /api/ingest/reingest
• Verb: POST
• Start a partial or metadata-only reingest.
• Parameters: JSON body
  • name: Name of the AIP. The AIP should also be found at %sharedDirectory%/tmp/<name>
  • uuid: UUID of the AIP to reingest
• Response: JSON
  • message: "Approval successful."
  • reingest_uuid: UUID of the reingested SIP

Copy Metadata

• URL: /api/ingest/copy_metadata_files/
• Verb: POST
• Add metadata files to a SIP.
• Parameters: JSON body
  • sip_uuid: UUID of the SIP to put files in
  • source_paths[]: List of files to be copied, base64 encoded, in the format 'source_location_uuid:full_path'
• Response: JSON
  • error: False
  • message: "Files added successfully."

Administration

Levels of Description

• URL: /api/administration/dips/atom/levels/
• Verb: GET?
• Returns a JSON-encoded set of the configured levels of description.
• Response: JSON. List of AtoM Levels of description with key 'UUID' and value 'name of level of description'.

Fetch Levels of Description

• URL: /api/administration/dips/atom/fetch_levels/
• Verb: GET?
• Fetch all levels of description from an AtoM database, replacing any previously existing.
• Response: JSON. Updated list of AtoM Levels of description with key 'UUID' and value 'name of level of description'.

Other

Path Metadata

• URL: /api/filesystem/metadata/
• Verb: GET, POST
• Fetch (GET) or update (POST) metadata for a path (currently only level of description).
• Parameters: Query string parameters (GET) or JSON body (POST)
  • path: Arranged path to get metadata on
• GET response: JSON
  • level_of_description: Level of description
• POST response: JSON
  • success: True

Processing Configuration

• URL: /api/processing-configuration/<name>
• Verb: GET?
• Return processing configuration with <name>
• Response: The processing config file as a stream.
• Content type: text/xml