API Summary in Preservica 6.3

Richard Smith | May 19th 2021
Share this post

In this post I'll give you a summary of what APIs we have in Preservica 6.3, and what new features you might be interested in. If you've been using Preservica for a while and just want to know what changed, you can look for the relevant paragraph at the end of each section, and for more details, you can look at the release notes from the three versions (6.2.1, 6.2.2 and 6.3). If you're new to the Preservica APIs then you can use the whole article as a reference.

Before we start I want to highlight that most of our APIs also have online documentation which you can get to from this index page.

Authentication API

Before you use any of our other APIs, you'll need to get an access token through this one.

In most cases that will mean submitting your user name and password to the /login endpoint. It's also a good idea to send the tenant – ask your Preservica contact if you don't know what your tenant name is. These parameters must be passed in the post body and the format must be x-www-form-urlencoded:

The response to this (assuming your credentials are valid) will give you a JSON response containing an access token:

    "success": true,
    "token": "0629571d-072b-4fce-bbeb-dc83e9a8ad0c",
    "refresh-token": "08437ed2-4bd1-489a-8d20-463544b05437",
    "validFor": 15,
    "user": ""

You can then use the access token (in the token field) to authenticate with our other APIs, by setting the Preservica-Access-Token custom header, or a Bearer type Authorization header.

If you include the optional parameter &includeUserDetails=true then you will receive additional information including the tenant and roles, which can be useful for building a user facing application:

    "success": true,
    "token": "215211d4-ab86-44aa-b355-5f02433d2018",
    "refresh-token": "31eed469-f95b-4930-af55-d3c6e7ccb31b",
    "validFor": 15,
    "user": "",
    "fullName": "Joe Bloggs",
    "email": "",
    "tenant": "INST",
    "roles": [
    "lastSuccessfulLogin": "2021-04-26T11:07:47.000+01:00"

Token Lifetime and Refresh

Newly created access tokens last for 15 minutes (this is the validFor field in the response). Before that token expires, you will need to generate a new one. You could just request a new token with credentials each time, but in a user facing scenario this means you need to request the password each time. Instead, it's better to use the refresh token with the /refresh endpoint.

Submit the current access token as the authentication, and the refresh token in the refreshToken parameter. You will receive a response similar to what you get from /login, with a new access token and new refresh token.

Note that unlike OAuth 2, you can't use a refresh token after the initial access token expires, so you can't wait for a 401 and then refresh, or have 'remember me' like functionality where you store a refresh token. You must proactively manage your token refreshes.

Changes since 6.2

  • The tenant parameter to /login is no longer mandatory, and the extended response includes the tenant.

Entity API

The Entity API is the main way we expose information about entities stored in your Preservica system. It is a RESTful XML API which has two main types of resource: resources returning a list, which will typically include a wrapper with an entry for each item in the list, and resources for a single object, which will include more details about the object. Responses typically include links to other relevant resources. List type resources often accept paging parameters (start and max).

Remember this article is not a full reference and for more details of available endpoints, visit the Swagger documentation!

If you want a read only view with more summary information presented to you, consider the Content API.

For example here is a response from /root/children, which is a list of entities:

<ChildrenResponse xmlns="" xmlns:xip="">
        <Child title="Library Collection" ref="c322f2c3-8f70-41ad-beb8-3506eac9fd23" type="SO"></Child>
        <Child title="Audio Recordings" ref="71143bfd-b29f-4548-871c-8334f2d2bcb8" type="SO"></Child>
        <Child title="Thomas Telford Exhibition" ref="1822b429-e792-4221-bfb3-86d754ad5249" type="SO"></Child>

Each item in the response list is a link to another resource, in this case an entity resource for the top level SOs, and the response also contains information about the paging and links to other relevant resources. And here is a sample entity details response:

<EntityResponse xmlns="" xmlns:xip="">
        <xip:Description>An image of Filey Brigg</xip:Description>
            <Fragment schema=""></Fragment>

In this case the response contains a single object (the XIP InformationObject) but there are more links to related resources.


Each of the three types of entity in the main object hierarchy (Structural Object, Information Object, Content Object) are available through similar routes, at /{object-type}/{ref}, e.g. /api/entity/information-objects/a9e1cae8-ea06-4157-8dd4-82d0525b031c. You can retrieve other information about an entity from the linked subresource endpoints. Remember that Folder and Asset are friendly names for SO and IO.

Information objects also contain information about representations (representations subresource and related requests). Content objects allow access to their generations and bitstreams (generations subresource and related requests), including downloading the content of individual bitstreams.

Making Changes

The Entity API also allows you to make changes. Most things you can change are made available as a POST request to a list resource (e.g. add an identifier through /.../identifiers) to create a new object, or a PUT request to an individual subresource (e.g. update metadata through /.../metadata/{mref} to update an existing one. To update something you'll typically need to get the relevant ID from a GET request to the list endpoint (/structural-objects/{entityRef}/metadata in this case).

There are also some endpoints that allow you to upload new content:

Events and Changed Entities

You can retrieve the event actions associated with a single entity from the /event-actions subresource of the entity. You can also reach events through the /events route, and the actions associated with a particular event by the /event-actions subresource of an event. (Reminder: A single event can have actions against multiple entities.) Event and event action listings are paged in the normal way.

You can also get a list of all the entities which have changed recently via /entities/updated-since. This is an alternative to the most common use of OAI-PMH and allows you to keep a UI or third party system up to date without having to re-inspect the entire entity tree.

Long Running Tasks, Actions and Progress Tokens

Some actions you can trigger may take longer than is reasonable to hold a REST request open for. This includes uploading content (which must pass through our ingest pipeline), and also actions which can affect a large part of the hierarchy (moving or locking the structure under an entity). These actions will return a progress token, which you can pass to the /progress/{token} endpoint to track the progress of the action. You'll have to poll this endpoint to get the status.

Sometimes these actions will also be made available in a list under /actions. For example, when you initiate an export by POSTing to /exports under an SO, as well as returning a progress token, it will also cause the export to appear at /actions/exports. If an action provides this type of endpoint it will give you more information than the general progress endpoint.

Some tasks may also create a process which you can watch via the Process Monitor API, but there is no link between progress tokens and processes so finding the right process can be difficult.

Access Control

Actions on entities, including viewing them, are controlled by the security tags on those entities, and the permissions that the current user's roles give them on those entities. For example to retrieve any part of an entity you need Read Metadata permission on its tag, and to update it you need Update Metadata permission on its tag.


A reminder that the Entity API is versioned (see this blog post for details of what that means). We have updated the version on both the Entity API XML schema ( and the XIP schema ( to reflect the new endpoints we've added and new information in XIP (Bitstream.OriginalName).

This means that:

  • If you're using the versioned endpoint at /api/entity/v6.2, nothing will change for you until you modify your code to request /api/entity/v6.3 instead. When you do that, you need to manage the new namespaces.
  • If you're using the unversioned endpoint, the responses will now serve the new namespace. If you're doing this, your code should be able to accept a change in namespace when we upgrade Preservica.

If you have a custom XIP to CMIS transform, you will have to change it to target XIP version 6.3. But before you do that, check whether you need it any more, as you can now set the metadata field to be used in Title and Description for Content API/CMIS object details requests, which was the main reason any of you were using custom XIP to CMIS transforms.

Changes since 6.2

  • Exports can be submitted on an SO or IO via /{entity-type}/{ref}/exports, and retrieved via /actions/exports
  • Retention management information is available under /retention-policies, /retention-events and the policy applied to an IO can be retrieved and managed at /.../retention-assignments.
  • Final deletion and recovery: final deletion can be manually triggered at /actions/final-deletions/, and deletion recovery at /actions/recoveries. Both endpoints accept the set of entities to perform the action on. These endpoints enable a Recycle Bin like behaviour.
  • Custom previews (thumbnails) can be uploaded and deleted on entities through /.../preview.

Content API

This API provides a read only view of your archive, search capabilities, asset download and information about entities suitable for a public access portal (in fact it backs our Universal Access portal). It is described in the SDK: Content API document as well as each endpoint being described in the Swagger doc.

Endpoints on this API typically take query parameters or a form encoded POST body, and return JSON.


Many requests on this API (obvious ones like /search and /search-within, but also those returning a list of entities at /top-level-list and /object-children) do a search against Preservica's search index. The form of all of these endpoints is similar, and the complexity is in creating the q parameter which defines the query. The Swagger doc for each of these requests describes how to set up the q parameter.

Search queries all permit you to send a POST request so the q parameter can be sent in the POST body, as it can be too long or complex to realistically put in a GET query.

The result from these endpoints gives you the objects that matched the search, and other information as requested in the query, e.g.:

  "success" : true,
  "version" : 1,
  "value" : {
    "objectIds" : [ "sdb:SO|866d4c6e-ee51-467a-b7a3-e4b65709cf95", "sdb:IO|a9e1cae8-ea06-4157-8dd4-82d0525b031c" ],
    "totalHits" : 2,
    "simpleChildSearch" : false,
    "metadata" : [ [ {
      "name" : "xip.title",
      "value" : "example so"
    } ], [ {
      "name" : "xip.title",
      "value" : "example io"
    } ] ]

The list of object IDs will be the same length as the metadata list, and you can merge those two lists together to get summary information you can display in the search result for each entity. You can also use this information together with the Entity API to retrieve more details about an object. Facet data will also be returned for each facet you request.

Object Details

The /object-details endpoint takes an object ID (with the sdb:IO type prefix) and gives you back metadata you can use to display the entity. The form of the response to this will be something like:

    "success": true,
    "version": 1,
    "value": {
        "id": "sdb:io|eb660290-fda0-40ae-a878-e82af22ce636",
        "name": "Image of Oxford city centre",
        "properties": [
                "name": "cmis:objectId",
                "value": "sdb:io|eb660290-fda0-40ae-a878-e82af22ce636"
                "name": "cmis:name",
                "value": "Image of Oxford city centre"
			// ...
        "metadata": {
            "title": "Image of Oxford city centre",
            "description": "A photo of High Street, Oxford",
            "groupOrItem" : [ {
              "title" : "DC Metadata",
              "groupOrItem" : [ {
                "name" : "subject",
                "value" : "The city of Oxford",
                "type" : "oai_dc.subject"
              }, {
                "name" : "publisher",
                "value" : "Joe Bloggs",
                "type" : "oai_dc.publisher"
              } ]
            } ]
        "links": [
                "rel": "render",
                "href": "",
                "type": "View Image"

The metadata that is returned is a result of running the CMIS transform for relevant descriptive metadata fragments (in this case I have set up an OAI DC to CMIS transform). There is an extensive set of cmis: and sdbcmis: properties which I won't go through here.

No changes since 6.2

Workflow API

This API lets you control most aspects of workflow management, including starting, stopping and terminating workflows, submitting results to tasks which normally require human interaction, and uploading definitions and contexts. This API is described in the SDK: Customisation API document as well as the individual endpoint documentation.

Note that requests to this API go to the /sdb webapp on the application server, not the API server as most of the other APIs. This is because workflows are managed in that webapp.

Changes in 6.3

  • The GET /instances endpoint now supports better filtering
  • Users with the Admin role can see the value of parameters (input and output) when retrieving a single instance, if you pass the relevant query options. Note that on our hosted systems, only Preservica staff have Admin role, so this is useful to EoP customers.

Process Monitor API

The Process Monitor API lets you see information about ongoing processes, messages associated with them, and a day-by-day history of long running processes (large ingests). It is most useful for tracking OPEX ingests, but normal ingests also create a Process which you can watch with this API. This API exposes the same information available through the Monitor webapp, or the Notifications panel on SDB and Explorer, if you have those enabled.

Report API

This is a new API which allows you to retrieve and run reports. Like the Entity API, it has a progress endpoint to allow you to track long running reports, and an /actions/reports endpoint to see running or completed reports.

Administration and Management API

This is a new API which allows you to perform some administrative and management tasks, which you'd normally do through the Administration menu in the main application: retrieval and management of schemas, documents and transforms (equivalent to the Schema Management page); management of thumbnail policy (on the Collection Properties page); and management of system properties (admin only – on hosted systems that means only our staff). EoP system administrators may also be interested in the /notify-updates endpoint to automatically update documents, workflows and reports when upgrading Preservica, but please talk to us before running this as it isn't yet ready for all scenarios.

User API

This API allows you to get information about your own user account after logging in (for example to display a Profile page in a UI), and to manage it (limited to requesting password resets at the moment).

Changes in 6.3

  • The password reset request no longer requires a tenant.

Storage API

You can use this API to discover your storage quota limit. This is currently only relevant in the context of Preservica Starter.

PAR (Registry) API

This API is for getting information from the Preservica Registry, and updating it if you have institution specific preservation needs. You need Registry Admin role to make any updates (which, on our hosted systems, is only available to Preservica staff). See this blog post on PAR for more information about PAR and how to use this API. Note that this API is on the Registry webapp (on the application server), not on the API webapp.

Changes in 6.3

  • We've added the concept of a Rule Set (/rulesets), which is a mapping of formats to business rules. A rule set is selectable on the Migration Settings page and encapsulates a common configuration of migration rules, for example 'normalisation rules for all raster image formats'.


OAI-PMH is a standard protocol through which archival systems can exchange information. Preservica exposes data as an OAI-PMH data provider through the /OAI-PMH route. This API is described in the SDK: Content API document.

The main use of OAI-PMH is to list recently changed records. If you aren't integrating with an OAI-PMH consumer, consider using /entities/updated-since on the Entity API.

Changes in 6.3

There are no design changes, but we've fixed some bugs around ListRecords not returning the right list of entities in some situations.


CMIS is a standard protocol through with content management systems can exchange information. Preservica exposes a limited subset of data through a read only CMIS 1.1 endpoint at /api/cmis/atom. (You can't use CMIS to create or update entities in Preservica.) The information available through CMIS is similar to that exposed by the Content API endpoints for top level entity listing, object details, searches and object children. Like the Content API, the information returned in the CMIS Metadata extension is generated from the relevant descriptive metadata fragments through their CMIS transform (e.g. a MODS to CMIS transform if you have MODS metadata).

The Content API is more widely used and more robust so consider using that if you aren't integrating with a CMIS consumer.

Changes in 6.3

There are no design changes, but we've fixed some bugs regarding the top level listing.

Open API library and latest developments on GitHub

Visit the Preservica GitHub page for our extensive API library, sample code, our latest open developments and more.

Visit our GitHub

Protecting the world’s digital memory

The world's cultural, economic, social and political memory is at risk. Preservica's mission is to protect it.

Learn more about Preservica