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

Beta endpoints

API endpoints which are still in-flux and that could potentially change.

Package

Provides additional functionality over the start and approve transfer endpoints, for example, wrapping both those steps into a single call.

• URL: /api/v2beta/package
• Verb: POST
• Start a new transfer type.
• Parameters: JSON body
  • name: Transfer name
  • type: Transfer type, e.g. standard, dataverse, zipped bag, default: standard
  • accession: Accession ID
  • accession_system_id: _
  • path: Path relative, or absolute to a storage service transfer source
  • metadata_set_id: _
  • auto_apptove: Boolean True or False to set the transfer to auto-approve, default: True
  • wait_until_complete: _
• Response: JSON
  • id: "Transfer UUID"

Examples: Only a subset of these options might be needed for most use-cases. A fundamental difference between the package endpoint and other's from which a transfer can be initiated is that a storage service transfer location UUID isn't always required. In some cases that might still be ideal. Starting a transfer using an absolute path:

  curl -v POST \
   -H "Authorization: ApiKey test:test" \
   -H "Content-Type: application/json" \
   -d "{\
       \"path\": \"$(echo -n '/home/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \
       \"name\": \"demo_transfer_absolute\", \
       \"processing_config\": \"automated\", \
       \"type\": \"standard\" \
       }" \
   "http://127.0.0.1:62080/api/v2beta/package"

Starting a transfer using an relative path with a transfer source UUID:

  curl -v POST \
   -H "Authorization: ApiKey test:test" \
   -H "Content-Type: application/json" \
   -d "{\
       \"path\": \"$(echo -n 'd1184f7f-d755-4c8d-831a-a3793b88f760:/archivematica/archivematica-sampledata/SampleTransfers/DemoTransfer' | base64 -w 0)\", \
       \"name\": \"demo_transfer_relative\", \
       \"processing_config\": \"automated\", \
       \"type\": \"standard\" \
       }" \
   "http://127.0.0.1:62080/api/v2beta/package"