Dissemination API

You can use the Dissemination API to find packages in the archive, read their metadata, and download their files. You can retrieve one package by its ID, browse the file plan, or search, either with a search configuration or with your own criteria.

Most calls return package objects with only the basics at first: the ID, the type, the title, the state, and the last QA decision, if there is one. To get more, such as the metadata or the files, you ask for enrichers.

Every call needs the headers in Common headers, and errors use the shape described in Errors. Some calls don't need a specific role. Every user who can call the API can use them, and you only see what your access to the packages allows. For where roles come from, see Authentication.

Ask for more information with enrichers

Send the enrichers that you want in the enrichers header, separated by commas and with no spaces, for example enrichers: metadata,representations.

Retrieve a package

You can retrieve one package, with the information that you ask for with enrichers.

GET /v2/aip/{packageId}

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

curl "https://archive.example.com/v2/aip/INV-2026-0042" \
  -H "Authorization: Bearer $TOKEN" \
  -H "tenant: example-tenant" \
  -H "enrichers: metadata,representations,retentionstatus"

Response: 200 OK with an AIP object.

{
  "packageId": "INV-2026-0042",
  "packageType": "AIP",
  "title": "Invoice 2026-0042",
  "state": "approved",
  "metadata": [
    {
      "schema": "dublincore",
      "fields": {
        "title": "Invoice 2026-0042",
        "creator": "Finance department"
      }
    }
  ],
  "representations": [
    {
      "id": "invoice-2026-0042.pdf",
      "data": [
        {
          "name": "invoice-2026-0042.pdf",
          "format": "application/pdf",
          "url": "https://archive.example.com/v2/content/q8Zr2kT0bWv1yXcN4mP7sA",
          "size": 48213
        }
      ]
    }
  ],
  "retentionStatus": {
    "trashed": false,
    "underLegalHold": false,
    "retentionRuleApplied": true,
    "retentionRuleIds": ["5b1e7c2a-0d3f-4a8e-b6c9-2f7a1d0e9b44"],
    "retentionRuleNames": ["Invoices: 7 years"],
    "retainUntil": "2033-10-05T00:00:00.000Z",
    "inDeletionList": false
  }
}

• 403 DOCUMENT_ACCESS_DENIED: you don't have read access to this package.

• 404 RESOURCE_NOT_FOUND: there's no package with this ID.

How a download works

You download a file through a link that the archive gives you in the package's details:

1. Retrieve the package with GET /v2/aip/{packageId} and the header enrichers: representations.

2. In representations, find the file in a representation's data list. Its url is the download link.

3. Call GET on that url, with the same Authorization and tenant headers as any other call.

Download a file

You can download the file behind a download link. By default, a link is valid for 24 hours.

GET /v2/content/{token}
GET /v2/content/{token}/stream

Both calls give you the same file. The /stream variant handles many downloads at the same time better, so use it for large files or for many parallel downloads.

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

Response: 200 OK with the file and its Content-Type. If the content store sends them, you also get Content-Length and a Content-Disposition with the file name.

With a Range header, you get 206 Partial Content and a Content-Range header instead.

curl "https://archive.example.com/v2/content/q8Zr2kT0bWv1yXcN4mP7sA" \
  -H "Authorization: Bearer $TOKEN" \
  -H "tenant: example-tenant" \
  -H "Range: bytes=0-1048575" \
  -o invoice-2026-0042.part

Both calls give these errors:

• 404 CONTENT_NOT_FOUND: the token isn't valid.

• 410 CONTENT_LINK_EXPIRED: the link is past its validity. Retrieve the package again to get a new link.

GET /v2/content/{token} also gives these errors:

• 404 CONTENT_NOT_FOUND: the file doesn't exist.

• 403 PERMISSION_DENIED: you don't have read access to the package.

• 416 RANGE_NOT_SATISFIABLE: the range is outside the file.

With /stream, a missing file or a range outside the file returns a plain 404 or 416, without the CONTENT_NOT_FOUND or RANGE_NOT_SATISFIABLE reason.

Browse the file plan

The file plan is the hierarchy that the archive arranges packages in. It starts with the root packages, and each package can have sub-packages.

List the root packages

GET /v2/fileplan

Required role: Any role.

Response: 200 OK with an AIPList object.

List the sub-packages of a package

GET /v2/fileplan/{packageId}

Required role: Any role.

Response: 200 OK with an AIPList object. If the package has no sub-packages, items is empty.

Tip: To see where a package sits in the file plan, retrieve it with the breadcrumb enricher.

Search with a search configuration

A search configuration is a ready-made search for your organization's packages. It decides which filters you can use and which columns each result has. You first list the search configurations, and then run a search with one of them.

List search configurations

GET /v2/search

Required role: Any role.

Response: 200 OK with an array of SearchConfig objects. Each one lists its filters and its columns.

Run a search

GET /v2/search/{searchConfig}

Required role: Any role.

curl "https://archive.example.com/v2/search/invoices?filter.dc_title=2026&filter.dc_created_min=2026-01-01T00:00:00Z&sortBy=dc:created&sortOrder=desc&pageSize=25" \
  -H "Authorization: Bearer $TOKEN" \
  -H "tenant: example-tenant" \
  -H "enrichers: searchcolumns"

Response: 200 OK with an AIPSearchResult object. If the search configuration has aggregate filters, aggregateBuckets gives the values that you can filter on, with the number of packages for each.

• 400 UNKNOWN_QUERY_FIELD: a filter name isn't in the search configuration.

• 400 INVALID_DATE: a date filter has a value that isn't a valid date.

• 404 SEARCH_CONFIG_NOT_FOUND: there's no search configuration with this name that you can use.

Filter the results

You add a filter as a query parameter, for example filter.dc_title=invoice. The name after filter. comes from the search configuration. Each filter in the search configuration has an operator that decides which name you use:

• Most operators: use filterName.

• BETWEEN: use filterMinName for the lower bound and filterMaxName for the upper bound, for example filter.dc_created_min=2026-01-01T00:00:00Z and filter.dc_created_max=2026-12-31T23:59:59Z.

• AGGREGATE: use filterName, with one of the values from aggregateBuckets. To pick several values, send a JSON array, URL-encoded. For example, ["invoice","credit note"] becomes filter.dc_nature_agg=%5B%22invoice%22,%22credit%20note%22%5D.

When you send several filters, a package must match all of them.

The filter's dataType decides the format of the value:

• date: a date in ISO 8601 format, for example 2026-10-05.

• datetime: a date and time in ISO 8601 format, for example 2026-10-05T09:00:00+02:00. Without an offset, the archive uses its own time zone.

Query string values must be URL-encoded. For example, write the + of an offset as %2B. Otherwise it arrives as a space, and you get 400 INVALID_DATE.

Export search results as CSV

You can run the same search and get the results as a CSV file, with one column for each column of the search configuration.

GET /v2/search/{searchConfig}/export

Required role: Any role.

The parameters are the same as for Run a search, without page and pageSize. Send the header enrichers: searchcolumns to fill the rows. Without it, the file holds only the row with the column labels.

Response: 200 OK with the CSV file (text/csv). The first row holds the column labels.

• 400 UNKNOWN_QUERY_FIELD: a filter name isn't in the search configuration.

• 404 SEARCH_CONFIG_NOT_FOUND: there's no search configuration with this name that you can use.

Search with your own criteria

When a search configuration doesn't fit, you can build your own query: a tree of rules on package fields, combined with AND and OR. Two calls work together:

1. Call GET /v2/query-fields to see which fields you can use, and which operators each field takes.

2. Send your criteria to POST /v2/search/aip.

List the fields that you can query

GET /v2/query-fields

Required role: archive-view

Response: 200 OK with a QueryFieldList. The list holds the columns and filters of the search configurations that you can use, and these fields that every package has:

{
  "items": [
    {
      "field": "dc:created",
      "label": "Created",
      "dataType": "datetime",
      "operators": ["EQ", "GT", "GTEQ", "LT", "LTEQ", "BETWEEN", "IN_LAST", "OLDER_THAN", "IS_NULL", "IS_NOT_NULL"],
      "sources": []
    },
    {
      "field": "inv:supplier",
      "label": "Supplier",
      "dataType": "string",
      "operators": ["EQ", "NEQ", "ILIKE", "IN", "NOT_IN", "IS_NULL", "IS_NOT_NULL"],
      "sources": ["invoices"]
    }
  ]
}

You can also query the files, the preservation actions, the signatures, and the submissions of a package. These fields aren't in the list. A rule on one of them matches when any entry matches. To find packages where no entry matches, use HAS_NONE_OF on the text fields. NEQ and NOT_IN aren't available on them.

Files

Preservation actions

Signatures

Submissions

Run a criteria search

You can find the packages that match your criteria, a page at a time.

POST /v2/search/aip

Required role: archive-content-manager

Body: an AipCriteriaSearchRequest.

Each rule in criteria.rules is either a condition or a nested group:

• A condition has a field, an operator, and, for most operators, a value.

• A group has a group with its own combinator and rules. Set negate to true to match the packages that don't match the group.

What you send as the value depends on the operator. The operators for pluginResult are in Rules on preservation results.

Some values need a specific format:

• ILIKE: finds the text anywhere in the field, in any case. If your value has % or _, the archive uses it as a pattern instead.

• IN_LAST and OLDER_THAN: a period in ISO 8601 format with one unit: days, weeks, months, or years, for example P7D, P2W, P3M, or P2Y. The archive counts back from the moment that the search runs.

• Dates: date fields take a date, such as 2026-10-05. datetime fields take a date and time, with or without an offset, or a date alone for the start of that day.

• Booleans: true or false.

A criteria tree can have up to 100 rules in total, and groups can go up to five levels deep.

Here's a search for invoices from the last 30 days that are PDF files or that had a failed preservation action, newest first:

{
  "criteria": {
    "combinator": "AND",
    "rules": [
      { "field": "aip:profile", "operator": "EQ", "value": "urn:example:profile:invoices" },
      { "field": "dc:created", "operator": "IN_LAST", "value": "P30D" },
      {
        "group": {
          "combinator": "OR",
          "rules": [
            {
              "field": "aip:representations/*/data/*/content/mime-type",
              "operator": "EQ",
              "value": "application/pdf"
            },
            { "field": "pluginResult", "plugin": "*", "operator": "EQ", "value": "FAILURE" }
          ]
        }
      }
    ]
  },
  "sort": [{ "field": "dc:created", "direction": "DESC" }],
  "page": 0,
  "pageSize": 50
}

Response: 200 OK with an AipCriteriaSearchResult. Each item also gives the values of the fields in your rules, in fields, so that you can show them as columns.

{
  "totalResults": 2,
  "page": 0,
  "pageSize": 50,
  "items": [
    {
      "packageId": "INV-2026-0042",
      "title": "Invoice 2026-0042",
      "type": "AIP",
      "created": "2026-10-05T09:14:10.000Z",
      "fields": {
        "aip:profile": "urn:example:profile:invoices",
        "aip:representations/*/data/*/content/mime-type": "application/pdf"
      }
    },
    {
      "packageId": "INV-2026-0039",
      "title": "Invoice 2026-0039",
      "type": "AIP",
      "created": "2026-09-28T15:02:51.000Z",
      "fields": {
        "aip:profile": "urn:example:profile:invoices",
        "aip:representations/*/data/*/content/mime-type": "image/tiff"
      }
    }
  ]
}

• 400 UNKNOWN_QUERY_FIELD: a field or a sort field isn't one that you can query.

• 400 OPERATOR_NOT_ALLOWED: the field doesn't take this operator.

• 400 REQUIRED_FIELD: a group has no combinator or no rules, or a condition has no field, operator, or value.

• 400 INVALID_QUERY_CRITERIA: the tree isn't valid. For example, a rule has both a condition and a group, there are too many rules, or groups are nested too deep. Other causes are a custom field path that isn't well formed, a BETWEEN without two values, and IN, NOT_IN, or HAS_NONE_OF without values.

• 400 INVALID_VALUE, INVALID_DATE, or INVALID_FORMAT: a value doesn't fit the field's data type, or a period isn't valid.

Rules on preservation results

The pluginResult field matches the result of one preservation action on a package. Two rule fields go with it:

• plugin: the name of the action, or * for any action.

• The value: SUCCESS, WARNING, or FAILURE.

It takes these operators:

• EQ with one value, or IN with values: the action has this result.

• NEVER_WAS with values: the action never had any of these results.

• NEVER_RAN: the action never ran on the package. This one needs a real action name, not *.

Rules on other fields

If you need another field, set custom to true on the rule and write the field path yourself, for example inv:costCenter. The path must look like prefix:name, with optional /segment parts, or you get 400 INVALID_QUERY_CRITERIA.

The archive treats a custom field as text. It takes these operators:

EQ, NEQ, ILIKE, STARTSWITH, IN, NOT_IN, HAS_NONE_OF, IS_NULL, and IS_NOT_NULL.

Save search filters

You can save a set of filter values for a search configuration, and use it again later. Saved filters are personal: you only see your own.

List your saved filters

GET /v2/search/saved

Required role: Any role.

Response: 200 OK with an array of SavedFilter objects, newest first.

Save a filter

POST /v2/search/saved

Required role: Any role.

Body: a SavedFilterInput.

{
  "name": "Invoices from 2026",
  "searchConfig": "invoices",
  "filters": {
    "dc_title": "2026",
    "dc_created_min": "2026-01-01T00:00:00Z"
  }
}

Response: 200 OK with the SavedFilter, with its id.

Update a saved filter

You can replace the name, the search configuration, and the filter values of a saved filter. If you leave out filters, the filter values stay as they are.

PUT /v2/search/saved/{filterId}

Required role: Any role.

Body: a SavedFilterInput.

Response: 200 OK with the updated SavedFilter.

• 404 RESOURCE_NOT_FOUND: there's no saved filter with this ID.

Delete a saved filter

DELETE /v2/search/saved/{filterId}

Required role: Any role.

Response: 204 No Content.

• 404 RESOURCE_NOT_FOUND: there's no saved filter with this ID.

Schemas

AIP

A package in the archive.

Lifecycle states

The state of a package is one of the following:

• ingesting: the archive is ingesting the package.

• pending_qa: the package waits for a QA reviewer.

• approved: the package passed ingest, and QA if the package needs it.

• rejected: a QA reviewer rejected the package.

• failed: the ingest failed.

• obsolete: the package is marked as obsolete.

• deleted: the package is deleted.

• legacy_approved: the package was archived before packages had a lifecycle. Treat it like approved.

QaDecision

MetadataSection

Representation

RepresentationFile

Breadcrumb

RetentionStatus

AipEvidence

The integrity evidence of a package. Which fields you get depends on the evidence that the package has. For the shape of the whole object, see Evidence example.

Evidence example

{
  "valid": true,
  "timestampChains": [
    {
      "timestamps": [
        {
          "genTime": "2026-10-05T09:20:00Z",
          "expiryTime": "2036-10-05T09:20:00Z",
          "issuer": "Example Timestamp Authority"
        }
      ]
    }
  ],
  "tree": {
    "partitionId": "2026-10",
    "submissions": [
      {
        "timestamp": "2026-10-05T09:15:00Z",
        "entries": {
          "invoice-2026-0042.pdf": {
            "hash": "3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b",
            "index": 0,
            "proof": [
              { "sibling": "n4bQgYhMfWWaL+qgxVrQFaO/TxsrC4Is0V1sFbDwCgg=", "position": "right" }
            ]
          }
        }
      }
    ]
  }
}

AIPList

AIPSearchResult

An AIPList with one more field:

AggregateBucket

SearchConfig

LinkedSearch

SearchFilter

SearchColumn

SavedFilter

SavedFilterInput

QueryFieldList

QueryField

AipCriteriaSearchRequest

The body of Run a criteria search.

QueryCriteria

QueryRule

Has either field and operator, or group.

SortSpec

AipCriteriaSearchResult

AipSearchItem