Archivematica 1.17.0 is our latest release.

Archivematica API

The Archivematica API provides:

  • Coverage of some basic workflow functionality.
  • Proxy support to the Storage Service.
  • Exposure to unit status or processing configuration details.

Resources and endpoints

Endpoints for the Archivematica API have been organized into the following resource categories:

Transfer

Transfer refers to the process of moving any set of digital objects into Archivematica and turning the materials into a Submission Information Package (SIP). The Transfer tab prepares your content for preservation in Archivematica.

Start transfer

POST /api/transfer/start_transfer/ Initiates a transfer in Archive matica.

Request body parameters:

Tip

The parameters in the following table can be submitted as a JSON object with key-value pairs in the request body.

name Name of transfer
type Type of the new transfer. Valid values are: standard, zipfile, unzipped bag, zipped bag, dspace, maildir, TRIM, dataverse. Default: standard.
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.
row_ids[] ID of the associated TransferMetadataSet for disk image ingest. Can be provided as [""].

Example request:

curl --request POST \
  http://my_archivematica_instance.archivematica.org/api/transfer/
  start_transfer/ \
  -H 'Authorization: ApiKey [_your_username_]:[_your_ApiKey_]' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'name=mc_api_transfer&type=standard&accession=2019-1234&paths%5B%5D='\
  ''M2JlYzc0MmYtMjBjMy00ZjBlLThjMzEtZGFmYTVlYzE4ZmRmOmNlbnRvcy9hcmNoaXZlbWF0aWNh
  LXNhbXBsZWRhdGEvU2FtcGxlVHJhbnNmZXJzL0RlbW9UcmFuc2ZlckNTVg%3D%3D'\''&rows_
  id%5B%5D='

Example response:

HTTP/1.1 200
status: 200
Server: nginx/1.12.2
Date: Thu, 15 Aug 2019 06:37:41 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Vary: Accept-Language, Cookie
Content-Language: en

{
    "path": "/var/archivematica/sharedDirectory/watchedDirectories/
    activeTransfers/standardTransfer/mc_api_transfer_1/",
    "message": "Copy successful."
}

List unapproved transfer(s)

GET /api/transfer/unapproved/ Returns a list of transfers awaiting approval

Response definitions:

message “Fetched unapproved transfers successfully.”  
results

List of dicts with the following keys:

type

directory

uuid

Transfer type.

One of: standard, zipfile, unzipped bag, zipped bag, dspace, maildir, TRIM, dataverse

Directory the transfer is in currently.

UUID of the transfer.

Example request:

  curl -X GET \
  http://my_archivematica_instance.archivematica.org/api/transfer/unapproved/ \
  -H 'Authorization: ApiKey [_your_username_]:[_your_ApiKey_]' \
  -H 'Content-Type: application/x-www-form-urlencoded'

Example response:

{
    "message": "Fetched unapproved transfers successfully.",
    "results": [
        {
            "directory": "mc-api-test-1",
            "type": "standard",
            "uuid": "f1bc64b5-5697-47fc-b3f3-ac92a1d1ebbb"
        },
        {
            "directory": "mc-api-test-2",
            "type": "standard",
            "uuid": "3ed192dc-8fa4-4698-ab03-00688a4a2553"
        }
    ]
}

Approve transfer(s)

POST /api/transfer/approve/ Approves a transfer awaiting initiation.

Request body parameters:

type Type of the transfer. Valid values are: standard, zipfile, unzipped bag, zipped bag, dspace, maildir, TRIM, dataverse. Default: standard.
directory Directory the transfer is in currently.

Example request:

curl -X POST \
  http://my_archivematica_instance.archivematica.org/api/transfer/approve/ \
  -H 'Authorization: ApiKey [_your_username_]:[_your_ApiKey_]' \
    -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Host: my_archivematica_instance.archivematica.org' \
   -d 'directory=mc-api-test-2&type=standard&rows_id%5B%5D='

Response definitions:

message “Approval successful.”
uuid UUID of the approved transfer

Example response:

{
    "message": "Approval successful.",
    "uuid": "a8791a46-ac73-4c7d-8c60-0673524226e3"
}

Status

GET /api/transfer/status/<transfer UUID>/ Returns the status of a transfer.

Response definitions:

status One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING string
name Name of the transfer, e.g. “imgs” string
sip_uuid If status is COMPLETE, this field will exist with either the UUID of the SIP or ‘BACKLOG’ string
microservice Name of the current microservice string
directory Name of the direcotry, e.g. “imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c” string
path Full path to the transfer, e.g. “/var/archivematica/sharedDirectory/watchedDirectories/SIPCreation/ completedTransfers/imgs-52dd0c01-e803-423a-be5f-b592b5d5d61c” string
message “Fetched status from <transfer UUID> successfully.” string
type “transfer” string
uuid UUID of the transfer, e.g. “52dd0c01-e803-423a-be5f-b592b5d5d61c” string

Note

For consumers of this endpoint, it is possible for Archivematica to return a status of COMPLETE without a sip_uuid. Consumers looking to use the UUID of the AIP that will be created following Ingest should therefore test for both a status of COMPLETE and the existence of sip_uuid that does not also equal BACKLOG to ensure that they retrieve it. This might mean an additional call to the status endpoint while this data becomes available.

Example request:

curl -X GET \
  http://my_archivematica_instance.archivematica.org/api/transfer/
  status/89fd478d-c896-461a-baec-5d1faf661020/ \
  -H 'Authorization: ApiKey [_your_username_]:[_your_ApiKey_]' \
  -H 'Host: my_archivematica_instance.archivematica.org'

Example response:

{
    "status": "COMPLETE",
    "name": "ab",
    "microservice": "Check transfer directory for objects",
    "directory": "ab-89fd478d-c896-461a-baec-5d1faf661020",
    "path": "/var/archivematica/sharedDirectory/watchedDirectories/SIPCreation/
    completedTransfers/ab-89fd478d-c896-461a-baec-5d1faf661020/",
    "message": "Fetched status for 89fd478d-c896-461a-baec-5d1faf661020
    successfully.",
    "type": "transfer",
    "uuid": "89fd478d-c896-461a-baec-5d1faf661020"
}

Hide

DELETE /api/transfer/<transfer UUID>/ delete/ Hides a transfer

Request body parameters:

transfer_uuid UUID of the transfer.

Response definitions:

removed Boolean true or false.

Example request:

curl -X DELETE \
    http://my_archivematica_instance.archivematica.org/api/transfer/
    89fd478d-c896-461a-baec-5d1faf661020/delete/ \
    -H 'Authorization: ApiKey [_your_username_]:[_your_ApiKey_]'

Example response:

{
    "removed": true
}

Completed

GET /api/transfer/completed/ Returns list of Transfers that are completed.

Response definitions:

message “Fetched completed transfers successfully.”
results List of UUIDs of completed Transfers.

Example request:

curl -X GET \
  http://test.archivematica.org/api/transfer/completed/ \
  -H 'Accept: */*' \
  -H 'Authorization: ApiKey [_your_username_]:[_your_ApiKey_]' \

Example response:

{
    "message": "Fetched completed transfers successfully.",
    "results": [
        "02ce3b9a-0704-4408-b0c0-2eb74a9f6652",
        "1557c65e-7e97-42a5-8e11-3d170d7ce435",
        "6db73922-0cc8-422d-81a6-b0b9bc0ff5f6",
        "72f7260e-a0aa-42cf-9e4c-fbb00c60d763",
        "89fd478d-c896-461a-baec-5d1faf661020",
        "8d961dac-8114-4c74-97e5-58264e34913f",
        "a58a60b3-9936-4233-b449-ab3620f4cf05",
        "b9af0b93-734d-41ca-a02d-024d17600d0b",
        "ce1c8af6-8395-46fb-a81d-6e08b50a58ee",
        "d2088fc6-7506-4012-ba0e-4f19880a1bfb",
        "e6efb7fb-eb27-4def-963e-31dfc2d55d61",
        "f4e12ba4-d2e2-4a4a-973c-7babd1da0cc4"
    ]
}

Start reingest

Note

The Start reingest endpoint complements the Reingest AIP endpoint on the Storage Service’s end. When a reingest has been initiated, Archivematica fetches the AIP from storage, extracts and runs fixity on it to verify its integrity. Then Archivematica will set up the environment as per the reingest type before the Storage Service endpoint calls the Archivematica Start reingest endpoint.

POST /api/transfer/reingest Starts a full reingest.

Request body parameters:

name Name of the AIP. The AIP should also be found at %sharedDirectory%/tmp/<name>.
uuid UUID of the AIP to reingest.

Response definitions:

message “Approval successful.”
reingest_uuid UUID of the reingested transfer.

Ingest

Ingest refers to the process by which digital objects are packaged into SIPs and run through microservices that enable normalization, packaging into an AIP, and generation of a DIP.

Status

GET /ingest/status/<unit_UUID>/ Returns status of the SIP.

Response definitions:

status One of FAILED, REJECTED, USER_INPUT, COMPLETE or PROCESSING.
name Name of the SIP, e.g. “imgs”.
microservices 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-b592b5d61c”.

Example request:

curl -X GET \
  http://my_archivematica_instance.archivematica.org/api/transfer/
  status/89fd478d-c896-461a-baec-5d1faf661020/ \
  -H 'Authorization: ApiKey [_your_username_]:[_your_ApiKey_]' \
  -H 'Host: my_archivematica_instance.archivematica.org'

Example response (JSON):

{
    "status": "COMPLETE",
    "name": "ab",
    "microservice": "Check transfer directory for objects",
    "directory": "ab-89fd478d-c896-461a-baec-5d1faf661020",
    "path": "/var/archivematica/sharedDirectory/watchedDirectories/SIPCreation/
    completedTransfers/ab-89fd478d-c896-461a-baec-5d1faf661020/",
    "message": "Fetched status for 89fd478d-c896-461a-baec-5d1faf661020
    successfully.",
    "type": "transfer",
    "uuid": "89fd478d-c896-461a-baec-5d1faf661020"
}

Hide

DELETE /api/ingest/<SIP UUID>/delete/ Hides a SIP.

Request body parameters:

sip_uuid UUID of the SIP.

Response definitions:

removed Boolean true or false.

Example request:

curl -X DELETE \
    http://my_archivematica_instance.archivematica.org/api/ingest/ \
    89fd478d-c896-461a-baec-5d1faf661020/delete/ \
    -H 'Authorization: ApiKey [_your_username_]:[_your_ApiKey_]'

Example response:

{
    "removed": true
}

List SIPS Waiting for User Input

GET /api/ingest/waiting Returns a list of SIPs waiting for user input.

Response definitions:

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.

Note

Despite the URL, this currently returns both SIPs & transfers that are waiting for user input. In the future, a separate /api/transfer/ waiting should be added for transfers.

Example request:

curl -X GET \
  http://mytestinstance.archivematica.net/api/ingest/waiting \
  -H 'Authorization: ApiKey admin:ooha0sshie8O' \
  -H 'Host: mytestinstsance.archivematica.net' \

Example response (JSON):

{
    "message": "Fetched units successfully.",
    "results": [
        {
            "microservice": "Approve standard transfer",
            "sip_name": "reingest",
            "sip_directory": "reingest",
            "sip_uuid": "affa2d71-3fdb-423f-8fe2-91c8d5ecc324"
        },
        {
            "microservice": "Approve standard transfer",
            "sip_name": "api-rein",
            "sip_directory": "api-rein",
            "sip_uuid": "e5a5808d-2ee8-4896-9ed5-1b692feb9b87"
        }
    ]
}

Completed

GET /api/ingest/completed/ Returns a list of completed SIPs.

Example request:

curl -X GET \
  http://mytestinstance.archivematica.net/api/transfer/completed/ \
  -H 'Accept: */*' \
  -H 'Authorization: ApiKey analyst:oui87nnmv' \
  -H 'Cache-Control: no-cache' \
  -H 'Connection: keep-alive' \
  -H 'Host: mytestinstance.archivematica.net' \
  -H 'cache-control: no-cache'

Example response (JSON):

{
    "message": "Fetched completed transfers successfully.",
    "results": [
        "8e15e1ff-e850-4a84-97b3-0eed0b535401",
        "de2692d2-05c6-4762-9708-38046699d870",
        "ee1ab6d9-0cb5-4641-8e7e-198ed2fb9db4"
    ]
}

Reingest

POST /api/ingest/reingest Starts a partial or metadata-only reingest.

Request body parameters:

name Name of the AIP. The AIP should also be found at %sharedDirectory%/tmp/<name>.
uuid UUID of the AIP to reingest.

Response definitions:

message “Approval successful.”
reingest_uuid UUID of the reingested transfer.

Example request:

curl -X POST \
  http://127.0.0.1:8000/api/v2/file/868a7ecd-c31b-4773-ad6d-d736a35b8a6e/
  reingest/ \
  -H 'Authorization: ApiKey analyst:ow7ioGh2reephua8uPaiWee4EiHeev6u' \
  -H 'Content-Type: application/json' \
  -H 'Host: 127.0.0.1:8000' \
  -d '{
    "pipeline":"85f9db99-b187-47c3-9b5b-fa35470104c4",
    "reingest_type":"FULL"
    }'

Example response (JSON):

{
    "error": false,
    "message": "Package 868a7ecd-c31b-4773-ad6d-d736a35b8a6e sent to pipeline
    Archivematica on test-vm (85f9db99-b187-47c3-9b5b-abc123)
    for re-ingest",
    "reingest_uuid": "affa2d71-3fdb-423f-8fe2-91c8d5ecc324",
    "status_code": 202
}

Copy metadata

POST /api/ingest/copy_metadata_files/ Adds metadata files to a SIP.

Request body parameters:

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 definitions:

error Boolean true or false.
message Success message or reason for the error.

Usage example:

curl -X POST \
    http://my_archivematica_instance.archivematica.org/api/ingest/copy_metadata_files/ \
    -H 'Authorization: ApiKey [_your_username_]:[_your_ApiKey_]' \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'sip_uuid=a7f1f36c-55c1-4fb7-a898-76d102e847dc&source_paths%5B%5D= \
    'NmRjYTgxNDAtMDg2NC00MzE5LTg2ZDctNTg0ZjZiZTY4N2EzOi9ob21lL2FyY2hpdmVtYXRpY2EvYXJjaGl2ZW1hdGljYS1zYW1wbGVkYXRhL2lzc3VlX3RlbXBsYXRlLm1k''

Response examples

201 Created:

{
  "error": false,
  "message": "Metadata files added successfully."
}

400 Bad Request:

{
  "error": true,
  "message": "sip_uuid and source_paths[] both required."
}

500 Internal Server Error:

{
  "error": true,
  "message": "Location 6dca8140-0864-4319-86d7-584f6be687a3 is not associated with this pipeline"
}

Administration

Administration enables you to configure various parts of the application and manage integrations and users.

Levels of description

GET /api/administration/dips/atom /levels/ Returns a JSON-encoded set of the configured levels of description.

Example request:

  curl -X GET \
  http://mytestinstance.archivematica.net/api/administration/dips/atom/levels/ \
  -H 'Accept: */*' \
  -H 'Authorization: ApiKey admin:oohah5chashie8Olkjhl998' \
  -H 'Cache-Control: no-cache' \
  -H 'Connection: keep-alive' \
  -H 'Host: mytestinstance.archivematica.net'

Example response (JSON):

The following response includes a list of AtoM Levels of description with key ‘UUID’ and value ‘name of level of description’.

[
    {
        "0a056204-1e35-11ea-887c-fa163e461c4e": "Collection"
    },
    {
        "0a056205-1e35-11ea-887c-fa163e461c4e": "File"
    },
    {
        "0a056206-1e35-11ea-887c-fa163e461c4e": "Fonds"
    },
    {
        "0a056207-1e35-11ea-887c-fa163e461c4e": "Item"
    },
    {
        "0a056208-1e35-11ea-887c-fa163e461c4e": "Part"
    },
    {
        "0a056209-1e35-11ea-887c-fa163e461c4e": "Record group"
    },
    {
        "0a05620a-1e35-11ea-887c-fa163e461c4e": "Series"
    },
    {
        "0a05620b-1e35-11ea-887c-fa163e461c4e": "Sous-fonds"
    },
    {
        "0a05620c-1e35-11ea-887c-fa163e461c4e": "Subseries"
    }
]

Fetch levels of description

GET /api/administration/dips/atom/fetch_levels/ Fetches all levels of description from an AtoM database, replacing any previously existing.

Example request:

curl -X GET \
  http://mytestinstance.archivematica.net/api/administration/dips/atom/fetch_levels/ \
  -H 'Accept: */*' \
  -H 'Authorization: ApiKey admin:oohah5chashie8OwEih6udie4shoolal' \
  -H 'Cache-Control: no-cache' \
  -H 'Connection: keep-alive' \
  -H 'Host: mytestinstance.archivematica.net' \
  -H 'Postman-Token: a6a5e394-ff95-46ff-9aca-233386024f20,e40e9ab1-3cb0-4de4-8da8-c6aeea862ea0' \
  -H 'User-Agent: PostmanRuntime/7.15.0' \
  -H 'accept-encoding: gzip, deflate' \
  -H 'cache-control: no-cache'

Example response (JSON):

The following response includes an updated list of AtoM Levels of description with key ‘UUID’ and value ‘name of level of description’.

[
    {
        "bfbc21c2-1e3b-11ea-887c-fa163e461c4e": "Collection"
    },
    {
        "bfbc21c3-1e3b-11ea-887c-fa163e461c4e": "File"
    },
    {
        "bfbc21c4-1e3b-11ea-887c-fa163e461c4e": "Fonds"
    },
    {
        "bfbc21c5-1e3b-11ea-887c-fa163e461c4e": "Item"
    },
    {
        "bfbc21c6-1e3b-11ea-887c-fa163e461c4e": "Part"
    },
    {
        "bfbc21c7-1e3b-11ea-887c-fa163e461c4e": "Record group"
    },
    {
        "bfbc21c8-1e3b-11ea-887c-fa163e461c4e": "Series"
    },
    {
        "bfbc21c9-1e3b-11ea-887c-fa163e461c4e": "Sous-fonds"
    },
    {
        "bfbc21ca-1e3b-11ea-887c-fa163e461c4e": "Subseries"
    }
]

Unit

Unit refers to “a type of Package Description that is specialized to provide information about an Archival Information Unit for use by Access Aids.” (OAIS, p.1-13, Section 1.7.2)

List jobs

GET /api/v2beta/jobs/<unit UUID>/ Returns a list of jobs for the passed unit (transfer or ingest).

Query string parameters (optional):

microservice Name of the microservice the jobs belong to.
link_uuid UUID of the job chain link.
name Name of the job.
detailed If the parameter is included in the request, the endpoint returns all the task properties provided by the Task endpoint.

Response definitions (from list of dicts):

uuid UUID of the job.
name Name of the job.
status One of USER_INPUT, PROCESSING, COMPLETE, FAILED or UNKNOWN.
microservice Microservice to which the job belongs.
link_uuid UUID of the job chain link.
tasks List of dicts with information about the microservice’s tasks.
uuid UUID of the task.
exit_code Exit code of the task.

Example request:

  curl -X GET \
  'http://mytestinstance.archivematica.net/api/v2beta/jobs/a06ac9b9-0d67-420a-befb-80ea9a562190/?name=Store%20the%20AIP&microservice=Store%20AIP&link uuid=a06ac9b9-0d67-420a-befb-80ea9a562190&link%20uuid=a06ac9b9-0d67-420a-befb-80ea9a562190' \
  -H 'Accept: */*' \
  -H 'Connection: keep-alive' \
  -H 'Host: mytestinstance.archivematica.net' \
  -H 'User-Agent: PostmanRuntime/7.15.0' \
  -H 'accept-encoding: gzip, deflate' \
  -H 'authorization: ApiKey analyst:oohah5chashie8OwEih6udie4choo3la' \
  -H 'cookie: csrftoken=sb52U8S35EpdB2T1K4lWXFl5jNnOrXrA' \
  -b csrftoken=sb52U8S35EpdB2T1K4lWXFl5jNnOrXrA

Example response (JSON body):

[
    {
        "status": "COMPLETE",
        "tasks": [
            {
                "uuid": "e37fcdc5-bac9-4790-8df1-bfcc6f7ec18a",
                "exit_code": 0
            }
        ],
        "uuid": "3e9e152c-340b-4f4d-9172-b1d29a655eae",
        "link_uuid": "20515483-25ed-4133-b23e-5bb14cab8e22",
        "microservice": "Store AIP",
        "name": "Store the AIP"
    }
]

Task

GET /api/v2beta/task/<task UUID>/ Returns information about a task.

Response definitions:

uuid UUID of the task.
exit_code List of dicts with keys:
file_uuid Exit code of the task.
file_name UUID of the file used for the task.
time_created File used for the task.
time_started String (YYYY-MM-DD HH:MM:SS) representing when the task was created.
duration Task duration in seconds (integer). If the duration is less than a second, this will be a < 1 string.

Example request:

curl -X GET \
  http://mytestinstance.archivematica.net/api/v2beta/task/93c70e84-fe97-4f31-bae0-8aaf7d1e6c6b/ \
  -H 'Accept: */*' \
  -H 'Cache-Control: no-cache' \
  -H 'Connection: keep-alive' \
  -H 'Host: mytestinstance.archivematica.net' \
  -H 'User-Agent: PostmanRuntime/7.15.0' \
  -H 'accept-encoding: gzip, deflate' \
  -H 'authorization: ApiKey test:oohah5chashie8OwEih6udie4choo3la' \
  -H 'cookie: csrftoken=sb52U8S35EpdB2T1K4lWXFl5jNnOrXrA' \
  -b csrftoken=sb52U8S35EpdB2T1K4lWXFl5jNnOrXrA

Example response (JSON):

{
    "uuid": "93c70e84-fe97-4f31-bae0-8aaf7d1e6c6b",
    "file_name": "BBhelmet.ai",
    "exit_code": 2,
    "time_created": "2020-01-17T00:44:37",
    "time_ended": "2020-01-17T00:44:40",
    "file_uuid": "5be8e4d0-6819-420f-ad17-b8ebd44e728d",
    "duration": 3,
    "time_started": "2020-01-17T00:44:37"
}

Other

Other is a generic resource category that includes path metadata associated with level of description, and it also includes name associated with any customized processing configuration.

Path metadata

GET, POST /api/filesystem/metadata/ Fetches (GET) or update (POST) metadata for a path (currently only level of description).

Query string parameters or request body parameters:

Tip

The following parameter can be submitted as query string parameter with GET or as a JSON object with a key-value pair in the request body with POST.

path Arranged path on which to get metadata.

Response: the processing config file as a stream

Content type: text/xml

Example request:

curl -X GET \
  http://mytestinstance.archivematica.net/api/v2beta/task/93c70e84-fe97-4f31-bae0-8aaf7d1e6c6b/ \
  -H 'Accept: */*' \
  -H 'Cache-Control: no-cache' \
  -H 'Connection: keep-alive' \
  -H 'Host: mytestinstance.archivematica.net' \
  -H 'User-Agent: PostmanRuntime/7.15.0' \
  -H 'accept-encoding: gzip, deflate' \
  -H 'authorization: ApiKey test:oohah5chashie8OwEih6udie4choo3la' \
  -H 'cookie: csrftoken=sb52U8S35EpdB2T1K4lWXFl5jNnOrXrA' \
  -b csrftoken=sb52U8S35EpdB2T1K4lWXFl5jNnOrXrA

Example response (JSON):

{
    "uuid": "93c70e84-fe97-4f31-bae0-8aaf7d1e6c6b",
    "file_name": "BBhelmet.ai",
    "exit_code": 2,
    "time_created": "2020-01-17T00:44:37",
    "time_ended": "2020-01-17T00:44:40",
    "file_uuid": "5be8e4d0-6819-420f-ad17-b8ebd44e728d",
    "duration": 3,
    "time_started": "2020-01-17T00:44:37"
}

Processing configuration

GET /api/processing-configuration/<name> Returns processing onfiguration with <name>

Example request:

curl \
    --location \
    --request GET \
    --header 'Authorization: ApiKey analyst:zzhah5chashie8OwEih6udie4choo4la' \
        'http://test.machine.archivematica.net/api/processing-configuration/backlog'

Example response:

<processingMCP>
    <preconfiguredChoices>
        <!-- Create SIP(s) -->
        <preconfiguredChoice>
            <appliesTo>bb194013-597c-4e4a-8493-b36d190f8717</appliesTo>
            <goToChain>7065d256-2f47-4b7d-baec-2c4699626121</goToChain>
        </preconfiguredChoice>
        <!-- Assign UUIDs to directories -->
        <preconfiguredChoice>
            <appliesTo>bd899573-694e-4d33-8c9b-df0af802437d</appliesTo>
            <goToChain>2dc3f487-e4b0-4e07-a4b3-6216ed24ca14</goToChain>
        </preconfiguredChoice>
        <!-- Send transfer to quarantine -->
        <preconfiguredChoice>
            <appliesTo>755b4177-c587-41a7-8c52-015277568302</appliesTo>
            <goToChain>d4404ab1-dc7f-4e9e-b1f8-aa861e766b8e</goToChain>
        </preconfiguredChoice>
    </preconfiguredChoices>
</processingMCP>

Content type: text/xml

Beta

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

Package

POST /api/v2beta/package Starts a new transfer type.

Request body parameters (mandatory):

name Transfer name.
path Path relative, or absolute to a storage service transfer source.

Request body parameters (optional):

type Transfer type. Valid values are: standard, zipfile, unzipped bag, zipped bag, dspace, maildir, TRIM, dataverse. Default: standard.
processing_config Processing configuration, e.g. default, automated, default: default
accession Accession ID.
access_system_id Access system ID (see Docs).
metadata_set_id Used to link to metadata sets added via the user interface. It’s safe to ignore this for now since metadata can’t be associated to transfer via the API at the moment.
auto_approve Boolean true or false to set the transfer to auto-approve, default: true.

Response definitions:

id Transfer UUID (Note: as the package endpoint allows the caller to interact with Archivematica asynchronously it does not guarantee a transfer has started. The caller must use the UUID in the response to verify it has begun or any errors that were encountered initiating one.)

Examples:

Only a subset of these options might be needed for most use-cases. A fundamental difference between the package endpoint and others from which a transfer can be initiated is that a storage service transfer source location’s UUID isn’t always required and the default transfer source location is used automatically.

When working with multiple transfer source locations, to start a transfer from a non-default location, you need to specify the location’s UUID.

Starting a transfer using an absolute path:

curl \
    --request POST \
    --header "Authorization: ApiKey test:test" \
    --header "Content-Type: application/json" \
    --data "{\
       \"path\": \"$(echo -n '/home/archivematica/archivematica-sampledata
       /SampleTransfers/DemoTransfer' | base64 -w 0)\", \
       \"name\": \"demo_transfer_absolute\", \
       \"processing_config\": \"automated\", \
       \"type\": \"standard\" \
      }" \
        "http://<archivematica-uri>/api/v2beta/package"

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

curl \
    --request POST \
    --header "Authorization: ApiKey test:test" \
    --header "Content-Type: application/json" \
    --data "{\
       \"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://<archivematica-uri>/api/v2beta/package"

Validate

/api/v2beta/validate/<validator>

Available in Archivematica 1.10+. This endpoint can be used to validate CSVs against embedded sets of rules. Currently works with Avalon Media System Manifest (``avalon``) and rights.csv (``rights``) files.

In the future, this endpoint can be extended to support validation for metadata.csv or archivesspaceids.csv, or other institutionally-based rules.

Response definitions:

valid Boolean true or false.
reason Includes validation error.

Usage example (assuming that avalon.csv exists):

curl \
  --data-binary "@avalon.csv" \
  --header "Authorization: ApiKey test:test" \
  --header "Content-Type: text/csv; charset=utf-8" \
    http://127.0.0.1:62080/api/v2beta/validate/avalon

Response examples

200 OK:

{
  "valid": true
}

400 Bad Request (expect reason to include different validation errors):

{
  "valid": false,
  "reason": "Administrative data must include reference name and author."
}

404 Not Found:

{
  "error": true,
  "message": "Unknown validator. Accepted values: avalon"
}