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
Ingest
Administration
Unit
Other
Beta

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"
}

Archivematica API¶

Resources and endpoints¶

Transfer¶

Start transfer¶

List unapproved transfer(s)¶

Approve transfer(s)¶

Status¶

Hide¶

Completed¶

Start reingest¶

Ingest¶

Status¶

Hide¶

List SIPS Waiting for User Input¶

Completed¶

Reingest¶

Copy metadata¶

Administration¶

Levels of description¶

Fetch levels of description¶

Unit¶

List jobs¶

Task¶

Other¶

Path metadata¶

Processing configuration¶

Beta¶

Package¶

Validate¶

Archivematica 1.16.0

Contents

Available projects

Archivematica

Archivematica Storage Service

License

Language

Archivematica API¶

Resources and endpoints¶

Transfer¶

Start transfer¶

List unapproved transfer(s)¶

Approve transfer(s)¶

Status¶

Hide¶

Completed¶

Start reingest¶

Ingest¶

Status¶

Hide¶

List SIPS Waiting for User Input¶

Completed¶

Reingest¶

Copy metadata¶

Administration¶

Levels of description¶

Fetch levels of description¶

Unit¶

List jobs¶

Task¶

Other¶

Path metadata¶

Processing configuration¶

Beta¶

Package¶

Validate¶

Archivematica 1.16.0

Contents

Search

Available projects

Archivematica

Archivematica Storage Service

License