Archive API

You can use the Archive API to look inside a package, move it through its lifecycle, and control who can reach it. Most calls act on one package, and you name it by its package ID in the path.

Two things to know first:

• A role lets you call an endpoint, but the archive also checks your permissions on the package itself. For example, you can only get a package's AIP structure if you can read that package.

• DIP exports and integrity reports run in the background. You start the job, poll its status, and then download the result. For the steps, see How a background job works.

Every call needs the headers in Common headers. To handle errors that any call can return, go to Errors.

How a background job works

A DIP export and an integrity report both follow the same three steps:

1. Start the job. You get 202 Accepted and an executionId right away, before the work is done.

2. Poll the status endpoint with that executionId until state is no longer RUNNING:

   • RUNNING: the job is still working.

   • COMPLETED: the result is ready to download.

   • ERROR: the job failed. There's no result to download.

3. Download the result. You get a ZIP file.

Only the person who started a job, or an administrator, can see its status and download its result. For anyone else, the job doesn't exist, and they get 404. A job also stops existing a limited time after it ends, so download the result soon after the job completes.

Get the full AIP structure

Returns the package's parts, organized the E-ARK way, with a download link for each file that you can still download. For the parts, see EarkAip.

GET /v2/archive/{packageId}

Required role: none. You need read access to the package.

Response: 200 OK with an EarkAip object.

{
  "packageId": "HR-2019-0042",
  "profile": "urn:example:profiles:hr-files-1.0",
  "mets": {
    "name": "METS.xml",
    "mimeType": "text/xml",
    "length": 5996,
    "digest": "3f2a9c41d0b7e85a6c19f04e2b7d3a18",
    "data-url": "https://archive.example.com/v2/content/Q2hhbmdlTWU"
  },
  "representations": [
    {
      "representationId": "rep1",
      "data": [
        {
          "format": {
            "name": "JPEG File Interchange Format",
            "puid": "fmt/43",
            "mimeType": "image/jpeg",
            "extensionMismatch": false
          },
          "content": {
            "name": "scan-001.jpg",
            "length": 652810,
            "data-url": "https://archive.example.com/v2/content/U2NhbjAwMQ"
          }
        }
      ]
    }
  ],
  "submissions": [
    {
      "submissionDate": "2026-03-02T09:14:00Z",
      "submitter": "jdoe",
      "content": {
        "name": "HR-2019-0042.zip",
        "length": 2481337,
        "data-url": "https://archive.example.com/v2/content/SFItMjAxOQ"
      }
    }
  ]
}

• 403 with DOCUMENT_ACCESS_DENIED: you can see the package, but you can't read it.

• 404 with RESOURCE_NOT_FOUND: no package that you can see has this ID.

Browse a package's structure

Returns one node for the package, with its title and the type FOLDER. The node has no children, metadata, or download links. To see the package's files, use Get the full AIP structure.

GET /v2/archive/{packageId}/structure

Required role: none. You need read access to the package.

Response: 200 OK with a PackageStructure object.

{
  "packageId": "HR-2019-0042",
  "root": {
    "name": "Personnel file J. Doe",
    "type": "FOLDER"
  }
}

• 403 with DOCUMENT_ACCESS_DENIED: you can see the package, but you can't read it.

• 404 with RESOURCE_NOT_FOUND: no package that you can see has this ID.

Manage the trash

When you delete a package, it goes to the trash first. From there, you can restore it or delete it permanently. A package under legal hold or retention can't go to the trash, and it can't be deleted permanently.

To move a package to the trash, restore it, or delete it permanently, you also need the ArchiveManage permission on the package. Without it, you get 403 with PERMISSION_DENIED.

Move a package to the trash

DELETE /v2/archive/{packageId}/trash

Required role: archive-content-manager

Response: 204 No Content.

• 404 with PACKAGE_NOT_FOUND: no package that you can see has this ID.

• 409 with LEGAL_HOLD_ACTIVE: the package is under legal hold.

• 409 with RETENTION_ACTIVE: the package is under retention.

List the packages in the trash

Returns the packages in the trash, most recently trashed first. All filters are optional, and you can combine them.

GET /v2/archive/trash

Required role: archive-content-manager

For from and to, you can send a date (2026-01-15), a date and time in UTC (2026-01-15T09:30:00), or a date and time with an offset (2026-01-15T09:30:00Z or 2026-01-15T09:30:00+01:00).

Response: 200 OK with a TrashedPackageList object.

{
  "totalResults": 1,
  "page": 0,
  "pageSize": 100,
  "items": [
    {
      "packageId": "HR-2019-0042",
      "title": "Personnel file J. Doe",
      "createdBy": "Human Resources",
      "trashedAt": "2026-09-14T13:02:11Z"
    }
  ]
}

• 400 with OUT_OF_RANGE: page is below 0, or pageSize is outside 1 to 1000.

• 400 with INVALID_SORT: sortOrder isn't asc or desc.

• 400 with INVALID_DATE: from or to isn't in one of the accepted date formats.

• 400 with INVALID_VALUE: from is later than to.

Restore a package from the trash

Takes the package out of the trash, so it's back in the archive.

POST /v2/archive/{packageId}/restore

Required role: archive-content-manager

Response: 204 No Content.

• 404 with PACKAGE_NOT_FOUND: no package in the trash that you can see has this ID.

Delete a package permanently

Deletes a package from the trash permanently. You can't undo it. To delete a package that's still in the archive, move it to the trash first.

DELETE /v2/archive/{packageId}/permanent

Required role: archive-content-manager

Response: 204 No Content.

• 404 with PACKAGE_NOT_FOUND: no package in the trash that you can see has this ID.

• 409 with LEGAL_HOLD_ACTIVE: the package is under legal hold.

• 409 with RETENTION_ACTIVE: the package is under retention.

Place or lift a legal hold

A legal hold keeps a package from being deleted, for example while a case is open. It has two effects:

• You can't move the package to the trash, or delete it permanently.

• When the package's retention period ends, its end action waits. The archive also doesn't add the package to a deletion list.

If the package is on a deletion list when you place the hold, the archive takes it off that list.

Place a legal hold

POST /v2/archive/{packageId}/legalhold

Required role: archive-records-manager or archive-records-reviewer. You also need the ManageLegalHold permission on the package.

Send a JSON body, even if it's empty ({}).

{
  "description": "Case 2026-117, pending litigation"
}

Response: 204 No Content.

• 403 with PERMISSION_DENIED: you don't have the ManageLegalHold permission on the package.

• 404 with RESOURCE_NOT_FOUND: no package that you can see has this ID.

Lift a legal hold

DELETE /v2/archive/{packageId}/legalhold

Required role: archive-records-manager or archive-records-reviewer. You also need the ManageLegalHold permission on the package.

Response: 204 No Content.

• 403 with PERMISSION_DENIED: you don't have the ManageLegalHold permission on the package.

• 404 with RESOURCE_NOT_FOUND: no package that you can see has this ID.

Decide on a package in QA review

When a package needs a QA review, it waits in the pending_qa state until a reviewer decides. You can send one of these decisions:

• approve: accepts the package, and its state changes to approved. Works on a package in pending_qa, and on a rejected package, to overturn an earlier rejection.

• reject: rejects the package, and its state changes to rejected. Works on a package in pending_qa.

• resubmit: sends a rejected package back to pending_qa, and clears the earlier decision.

POST /v2/archive/{packageId}/qa-decision

Required role: archive-qa. You also need the ArchiveQA permission on the package.

{
  "transition": "reject",
  "reason": "The scan of page 4 is unreadable."
}

Response: 204 No Content.

• 400 with VALIDATION_ERROR: transition is missing.

• 403 with PERMISSION_DENIED: you don't have the ArchiveQA permission on the package.

• 404 with RESOURCE_NOT_FOUND: no package that you can see has this ID.

• 409 with STATE_CONFLICT: the package's state doesn't allow this decision, for example reject on a package that's already approved.

Transfer a package to another tenant

A tenant is a separate archive, with its own packages. When you transfer a package, the archive sends a copy of it to the target tenant, which ingests it as a new SIP. The package stays in your tenant too, and its sub-packages aren't transferred.

List the tenants that you can reach

Returns the tenants that you have access to, including the one that you're calling. Use an id from this list as the target of a transfer.

GET /v2/archive/tenants

Required role: none.

Response: 200 OK with a TenantList object.

{
  "items": [
    {
      "id": "acme-archive",
      "label": "ACME Archive",
      "current": true
    },
    {
      "id": "acme-records",
      "label": "ACME Records",
      "current": false
    }
  ]
}

Transfer a package

POST /v2/archive/{packageId}/transfer

Required role: archive-content-manager. You also need the ArchiveManage permission on the package.

{
  "targetTenantId": "acme-records"
}

Response: 204 No Content.

• 403 with PERMISSION_DENIED: you don't have the ArchiveManage permission on the package.

• 404 with RESOURCE_NOT_FOUND: no package that you can see has this ID.

• 409 with PACKAGE_ALREADY_TRANSFERRED: the package was already transferred to this tenant.

Export a package as a DIP

A DIP export runs in the background and gives you one ZIP file with the package's files and descriptive metadata, and those of its sub-packages. For the steps, see How a background job works.

Start a DIP export

POST /v2/archive/{packageId}/dip-export

Required role: none. You need the ArchiveManage permission on the package.

Response: 202 Accepted with the executionId of the export.

{
  "executionId": "6f1c2a7e-3b9d-4e15-a0c8-91d2f4b7e630"
}

• 403 with PERMISSION_DENIED: you don't have the ArchiveManage permission on the package.

• 404 with RESOURCE_NOT_FOUND: no package that you can see has this ID.

Get the status of a DIP export

GET /v2/archive/dip-exports/{executionId}/status

Required role: none. You must have started the export, or be an administrator: see How a background job works.

Response: 200 OK with the executionId and the state: RUNNING, COMPLETED, or ERROR.

{
  "executionId": "6f1c2a7e-3b9d-4e15-a0c8-91d2f4b7e630",
  "state": "COMPLETED"
}

• 404 with RESOURCE_NOT_FOUND: the export doesn't exist for you.

Download a DIP export

GET /v2/archive/dip-exports/{executionId}/result

Required role: none. You must have started the export, or be an administrator.

Response: 200 OK with the ZIP file (application/zip), as an attachment named dip-export-{executionId}.zip.

curl -o dip-export.zip \
  -H "Authorization: Bearer $TOKEN" \
  -H "tenant: acme-archive" \
  https://archive.example.com/v2/archive/dip-exports/6f1c2a7e-3b9d-4e15-a0c8-91d2f4b7e630/result

• 404 with RESOURCE_NOT_FOUND: the export doesn't exist for you, or the job hasn't completed.

Create an integrity report

An integrity report shows whether one or more packages are still intact. It does the following checks on each package, and the archive then seals the report:

• Recalculates the checksum of each file, and compares it with the checksum recorded at ingest.

• Checks the package's audit trail.

• Validates the package's evidence records.

• Validates the signatures in the package's files.

The report runs in the background. For the steps, see How a background job works.

Start an integrity report

POST /v2/archive/integrity-report

Required role: archive-content-manager. You also need the ArchiveManage permission on each package.

{
  "packageIds": ["HR-2019-0042", "HR-2019-0043"],
  "qualified": false
}

Response: 202 Accepted with the executionId of the report.

{
  "executionId": "b8e4d0f2-71a6-4c39-9e5d-2a0f6c8b1d47"
}

• 400 with VALIDATION_ERROR: packageIds is missing.

• 400 with OUT_OF_RANGE: packageIds is empty.

• 403 with PERMISSION_DENIED: you don't have the ArchiveManage permission on one of the packages.

• 404 with RESOURCE_NOT_FOUND: one of the package IDs isn't a package that you can see. The archive doesn't start the report.

Get the status of an integrity report

GET /v2/archive/integrity-reports/{executionId}/status

Required role: archive-content-manager. You must also have started the report, or be an administrator: see How a background job works.

Response: 200 OK with the executionId and the state: RUNNING, COMPLETED, or ERROR.

• 404 with RESOURCE_NOT_FOUND: the report doesn't exist for you.

Download an integrity report

GET /v2/archive/integrity-reports/{executionId}/result

Required role: archive-content-manager. You must also have started the report, or be an administrator.

Response: 200 OK with a ZIP file (application/zip), as an attachment named integrity-report-{executionId}.zip. The ZIP contains the report as JSON and as a PDF. It also contains the detached electronic seal over the report, and the timestamp token over that seal.

• 404 with RESOURCE_NOT_FOUND: the report doesn't exist for you, or the job hasn't completed.

Manage permissions on a package

Users normally reach packages through their roles, and through the permissions that a package inherits. You can also give a user or a group a permission on one package, permanently or for a time frame. You can also share the package with someone outside the archive by email.

Every permission call returns 200 OK with the package's permissions after the change, as a PermissionList object.

Most of these calls need no role, but they check your permissions on the package:

• To see its permissions, you need read access to the package.

• To change them, you need the ArchiveShare permission on the package. You can only grant a permission that you hold on the package yourself. Administrators are exempt from both rules.

• Adding a permission and sharing by email also need a role, which the call states.

You can grant these permissions:

Get the permissions

GET /v2/archive/{packageId}/permissions

{
  "blockInheritance": false,
  "entries": [
    {
      "principal": "hr-team",
      "permission": "ArchiveRead",
      "source": "LOCAL",
      "grantedBy": "jdoe",
      "timeframe": {
        "begin": "2026-10-01T00:00:00Z",
        "end": "2026-12-31T23:59:59Z"
      }
    },
    {
      "principal": "transient/auditor@example.com",
      "permission": "ArchiveRead",
      "source": "EXTERNAL",
      "grantedBy": "jdoe",
      "timeframe": {
        "end": "2026-11-30T23:59:59Z"
      }
    }
  ]
}

• 403 with DOCUMENT_ACCESS_DENIED: you can see the package, but you can't read it.

• 404 with RESOURCE_NOT_FOUND: no package that you can see has this ID.

Add a permission

Adds one entry to the package. The other entries stay as they are.

POST /v2/archive/{packageId}/permissions

Required role: archive-content-manager. You also need the ArchiveShare permission on the package.

{
  "principal": "hr-team",
  "permission": "ArchiveRead",
  "timeframe": {
    "begin": "2026-10-01T00:00:00Z",
    "end": "2026-12-31T23:59:59Z"
  },
  "notify": true,
  "comment": "Access for the yearly HR review."
}

• 400 with VALIDATION_ERROR: principal or permission is missing.

• 403 with PERMISSION_DENIED: you don't have the required role, you can't share permissions on this package, or you can't grant this permission.

• 404 with RESOURCE_NOT_FOUND: no package that you can see has this ID.

Remove a permission

Removes the package's own entries for one user or group. Inherited entries stay. If nothing matches, you get the list unchanged.

DELETE /v2/archive/{packageId}/permissions?principal={principal}

• 403 with PERMISSION_DENIED: there's an entry to remove, but you can't share permissions on this package.

• 404 with RESOURCE_NOT_FOUND: no package that you can see has this ID.

Block or unblock inherited permissions

Blocking stops the package from inheriting permissions, so only its own entries (LOCAL and EXTERNAL) apply. Unblocking turns inheritance back on.

POST /v2/archive/{packageId}/permissions/block-inheritance
DELETE /v2/archive/{packageId}/permissions/block-inheritance

In the response, blockInheritance shows whether inheritance is blocked.

• 403 with PERMISSION_DENIED: you can't share permissions on this package.

• 404 with RESOURCE_NOT_FOUND: no package that you can see has this ID.

Share a package by email

Gives a permission to someone by email address, even if they don't have an account in the archive. A share needs an end date, and the recipient gets an email about it. They have the permission that you chose, from timeframe.begin (or right away) until timeframe.end.

POST /v2/archive/{packageId}/permissions/share

Required role: archive-content-manager. You also need the ArchiveShare permission on the package.

{
  "email": "auditor@example.com",
  "permission": "ArchiveRead",
  "timeframe": {
    "end": "2026-11-30T23:59:59Z"
  },
  "comment": "Here's the file for the external audit."
}

In the response, the share shows with source set to EXTERNAL, and a principal that starts with transient/ and the email address.

• 400 with REQUIRED_FIELD: timeframe is sent without end.

• 400 with VALIDATION_ERROR: email, permission, or timeframe is missing.

• 403 with PERMISSION_DENIED: you don't have the required role, you can't share permissions on this package, or you can't grant this permission.

• 404 with RESOURCE_NOT_FOUND: no package that you can see has this ID.

Revoke a share

Removes every share of the package with this email address. If there's none, you get the list unchanged.

DELETE /v2/archive/{packageId}/permissions/share?email={email}

• 403 with PERMISSION_DENIED: there's a share to revoke, but you can't share permissions on this package.

• 404 with RESOURCE_NOT_FOUND: no package that you can see has this ID.

Schemas

EarkAip

ContentFile

EarkMetadata

EarkRepresentation

EarkDataFile

EarkFormat

EarkSubmission

SignaturesInfo

Signature

Signer

Each field comes from the signer's certificate, and is missing when the certificate doesn't hold it. Besides the fields in the table, a signer can have commonName, givenName, surname, pseudonym, title, email, organizationName, organizationalUnit, locality, state, and countryName, as strings.

PackageStructure

PackageNode

TrashedPackageList

TrashedPackage

TenantList

Tenant

DipExportStatus and IntegrityReportStatus

The status calls of a DIP export and of an integrity report return the same fields.

PermissionList

PermissionEntry

PermissionTimeframe