Preservica API Documentation

/admin Administration and Management API

API for administration and management tasks

This is an XML API. Use this API to perform administrative and management tasks, which you'd normally do through the Administration menu in the main application. Several endpoints on this API are 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.

Management actions you can do through this API (with a Manager role) include:

Uploading and managing schemas, transforms and documents (but not forms and groups for NGI metadata configuration, that is the Metadata API)
Thumbnail policy configuration
Security configuration: tags, roles and the security matrix to assign permissions by tag/role
User management (as long as you aren't using external authentication like SAML)
Two factor authentication policy and user management

Temporary Users

The endpoints under /temporary-users allow you to create and manage temporary users on your tenant.

Temporary users don't log in through the login page. Instead, you get a TemporaryUserToken, which you can submit to /acquire-temporary-user on the Access Token API. Typically, you would provide this token in a link to a user (perhaps by email or through a Discord bot sending a private message), and have a page in your portal which uses that endpoint to create a session.

/accesstoken Authentication API

API for managing user authentication.

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 – if you don't know what your tenant name is, log in once without it but requesting the user details, which includes it. These parameters must be passed in the post body and the format must be x-www-form-urlencoded:

[email protected]&password=xyz&tenant=INST

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": "[email protected]"
}

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": "[email protected]",
    "fullName": "Joe Bloggs",
    "email": "[email protected]",
    "tenant": "INST",
    "tenantValue": "686ef128f436af3d9354d18a7aaec0aa"
    "roles": [
        "ROLE_SDB_MANAGER_USER",
        "ROLE_SDB_REGISTRY_ADMIN_USER"
    ],
    "lastSuccessfulLogin": "2021-04-26T11:07:47.000+01:00"
}

If you're already logged in you can also get this information from /api/user/details.

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.

Cookie Based Authentication

If you are using the APIs in a context where cookies are supported, for example in a user facing browser application or using libraries that support cookies, you can request that our API saves a cookie with your access token. This cookie won't be accessible to script, making it harder to hijack or steal with a XSS attack on your site. To use the APIs in this way:

Make your login request passing cookie=true. If you're using the /login (or temporary users, see the Admin API) endpoint, this also needs to be in the POST body.
When you need to refresh your token, you can call /refresh with cookie=true, and no refresh token. Your access token cookie will be refreshed if necessary. This will keep your session alive, so you are responsible for ensuring your session management aligns with appropriate security policies around session timeouts.

Your script doesn't need to know about the access token at all.

Two Factor Authentication

If 2FA is enabled on a tenant, your API logins will have to perform 2FA as well. (Accounts which only have the Anonymous role are an exception, so you can serve a public anonymous portal like our UA/Portal with API logins.) If you want to use a service account for automated scripting, you should keep the credentials and the token generating key separate, otherwise you don't really have two factors! For a user facing application you should prompt the user for the second factor.

In terms of the mechanics of authenticating with 2FA:

The request to /login (or other initial login endpoints) will return a HTTP 401 (because your authentication is not complete), the message will contain "needs.2fa", and the value will include a continuation-token.
You should prompt the user (or generate, for a non-interactive service) the 2FA six digit token and submit it to complete-2fa endpoint. Our 2FA follows RFC4226/6328 for time based one time passwords (the same as Google Authenticator etc). Because it's time based, if you're generating a token, make sure the clock on the system is accurate.
If you receive "needs.2fa.setup" rather than "needs.2fa", the response will also contain a secretKey. This is the authenticator key which you should save, or show to the user in a way that they can save (e.g. we use it to show a QR code that an authenticator app can save). As above, you need to generate or prompt for a valid authenticator code using this key and make a call to complete-2fa. Once you successfully call complete-2fa, the authenticator key will be saved against that user and future login requests will require it.
The response from complete-2fa is the same as you get from login if 2FA is disabled, containing an access token that you can use as normal.
You will also get a cookie (Preservica_2FA_{user-hash}) set. You can pass this to future /login requests to skip 2FA if you already did it within the persistence time. This is most useful if you are using the API to back a user facing application. You can safely send all these cookies with different hashes to the API, only the one for the right user will be inspected.
Failures: If a user enters an incorrect code too many (3) times, their account will be locked and a manager will need to unlock them from the 2FA configuration page. The number of failures and maximum attempts will be returned in the failure response.

There are more details in this blog post by Andy from our CX team.

Logging Out

Your access token will expire after 15 minutes if you don't refresh it. For many use cases, this is good enough. But if you want to force a session to close, you can call close-current, or revoke.

External Authentication

If you want to support SAML in a user facing portal, don't use this API to do it – instead, you should forward your users to /auth/login (or /auth/login/{tenant-value}) and allow our auth service to manage the SAML interaction. A successful authentication loop there will set the access-token cookie which can be used to authenticate with our APIs.

This approach is deprecated and you should use an alternative if possible. You can use acquire-external to assert a user identity when you don't have credentials, for example if you are managing an external authentication integration that Preservica doesn't support. You need to share a secret between Preservica (in system properties) and your integration, and it is extremely important to keep this secret secure as it enables logging in as any user on your tenant.

/auth Auth Management API

API for managing authentication configuration.

Use this API to manage authentication configuration, in particular information allowing you to set up SAML. Most endpoints require tenant manager permissions. Note that some configuration types are only available on higher editions.

The /configuration endpoints show or control what authentication to apply.

LDAP

By default, all tenants use LDAP for authentication. The LDAP parameters are set by the system operator (in local.properties). To return your tenant to use LDAP only, post a simple LDAP configuration:

{
  "authType" : "LDAP"
}

You can always log in with accounts defined in LDAP, even if your configuration is something else (e.g. SAML). API logins through the Access Token API will work as normal. To access the login page for interactive login when using SAML, use ?type=LDAP in the query string in the URL.

SAML

SAML is a protocol that allows authentication to be delegated. It allows users to log in with an existing account, without Preservica needing to have a copy of your credentials, or having to manage user accounts inside Preservica. Many of you are large organisations who will already have a lot of users and you would like to have cloud systems (like us) use the same authentication provider as you do internally (for example your Microsoft Entra ID). SAML is a secure and standard way to do that.

For SAML to work, the Service Provider (SP) – the application the user wants to use, in this case Preservica – sends a request to the Identity Provider (IdP) – the system that handles authentication, e.g. your Entra ID controller. The user then logs in through the IdP, for example with a Microsoft account. The IdP confirms their details and sends an assertion to the SP, containing information about the user such as roles. This requires both the IdP and SP to be configured to know about and trust each other.

IdP configuration

Before configuring Preservica, you need to set up your IdP to register Preservica as an application it supports authenticating for. How you do this varies between IdPs, but you will need at least the Assertion Consumer Service (ACS) URL from Preservica, and likely the EntityID too. You can retrieve this from the API at sp-metadata, or get the XML descriptor at /auth/saml/sp-metadata when logged in.

Preservica configuration with metadata URL

If your IdP exposes the federated metadata document, you can PUT a configuration referring to that metadata and the metadata document will be read to populate the rest of the configuration:

{
  "authType" : "SAML",
  "authProviderUrl" : "https://sample-idp/app-metadata/abcd"
}

The response will contain the information that was extracted, e.g.

{
  "authType" : "SAML",
  "authProviderUrl" : "https://sample-idp/app-metadata/abcd",
  "samlParameters" : {
    "samlIdpMetadata" : {
      "entityId" : "https://sample-idp/app-metadata/abcd",
      "ssoUrl" : "https://sample-idp/app-metadata/abcd/saml-login",
      "singleLogoutUrl" : "https://sample-idp/app-metadata/abcd/saml-logout",
      "certificates" : [ "MIIC/TCCAeWgAwIBAgIJYyH4LK6Q...VQp4COLibvLw==" ]
    }
  }
}

Preservica configuration with metadata XML

Sometimes, the IdP metadata document is not available from a URL. In this case, you will have to transfer the file manually and update the configuration with those values.

First, make a call to POST idp-metadata, sending the XML document in the POST body. This will return the idpMetadata section of the SAML parameters object. Then, PUT a configuration containing that IdP metadata:

{
	"authType": "SAML",
	"samlParameters": {
		"samlIdpMetadata": { /* the content you got from idp-metadata */ }
	}
}

Attribute mapping

The SAML assertion contains information about the user in attributes. Preservica has defaults for which attributes it should take user information from, but you can override this mapping if your IdP is configured differently. Use the attributeMappings element with the SAML parameters:

  "samlParameters": {
    /* ... */
    "attributeMappings": {
      "identifier" : "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn",
      "displayName" : "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
      "email" : "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
      "roles" : "http://schemas.microsoft.com/ws/2008/06/identity/claims/groups"
    }
  }

For the user name (identifier), if the attribute value isn't available Preservica will use the NameID from the assertion instead.

Signed requests and certificate management

For some use cases you may wish to digitally sign the requests Preservica makes to the IdP. You might not need this extra level of trust, but your policy or IdP may require it. In this case, you can select a certificate and key pair for signing:

{
  "authType" : "SAML",
  "authProviderUrl" : "https://sample-idp/app-metadata/abcd",
  "samlParameters" : {
    "signedRequests" : {
      "sign" : true,
      "certificate" : "d8ca09f07b49fe24dd93233e12853bf1"
    }
  }
}

The certificate ID is the one returned in a call to GET certificates. You'll have to upload a certificate and key pair via POST certificates before you can use it.

Context classes

SAML assertions can include information from the IdP about how the login was performed in the AuthnContextClassRef element. You can specify that SAML logins must have a particular context class:

{
  "authType" : "SAML",
  "authProviderUrl" : "https://sample-idp/app-metadata/abcd",
  "samlParameters" : {
    "validContextClasses" : [ "urn:oasis:names:tc:SAML:2.0:ac:classes:SmartcardPKI", "urn:oasis:names:tc:SAML:2.0:ac:classes:SoftwarePKI" ]
  }
}

The assertion must have at least one of the classes specified, otherwise the login will be rejected.

Options

Some additional aspects of SAML authentication can be configured for non-standard use cases through the options element. This is an array of string options, e.g.:

{
  "authType" : "SAML",
  "authProviderUrl" : "https://sample-idp/app-metadata/abcd",
  "samlParameters" : {
    "options" : [ "role-attribute-comma-separated" ]
  }
}

Available options:

role-attribute-comma-separated: Normally, the roles returned from an IdP in a SAML attribute should be in multiple values, one per role. Some IdPs can't easily be configured this way and put all the roles into a single value, comma separated. This option instructs the SAML assertion processor to expect roles in that form.

Role mapping

If you assign roles to the user in your authentication provider, they will be used by Preservica. Roles coming from LDAP will be prefixed with ROLE_, but those coming from external providers like SAML won't, so you'll need to add the prefix to your mapping.

Role mapping doesn't apply to LDAP authentication.

When users have group memberships in your authentication provider and you don't want to assign roles specific to Preservica, you can map those groups or roles to Preservica roles with the roleMapping option. It is a map of source roles to a list of Preservica roles, e.g.

{
  "authType" : "SAML",
  "authProviderUrl" : "https://sample-idp/app-metadata/abcd",
  "roleMappings" : {
    "IdP Manager Role" : [ "ROLE_SDB_MANAGER_USER" ],
    "IdP Archivist Role" : [ "ROLE_SDB_INGEST_USER", "ROLE_SDB_TRANSFORM_USER", "ROLE_SDB_ACCESS_USER", "ROLE_SDB_DATA_MANAGEMENT_USER" ]
  }
}

Unless you have Preservica installed on premise you won't be able to map or assign the Admin or Registry Admin role.

Role Filtering

It is possible to filter roles coming from the external authentication provider by providing a prefix or prefixes you wish to match. This can be useful when the authentication provider is used for multiple applications and only a subset of roles are required for Preservica.

Any roles that do not start with one of the provided prefixes will be ignored for the authentication session. If no role filters are provided then all roles will be accepted.

Role filtering will take place after role mapping.

{
  "authType" : "LDAP",
  "roleFilterPrefixes" : [ "ROLE_SDB_", "OTHER_ROLE_" ]
}

/analytics Analytics API

API for getting analytics data.

This API offers data sets that you can use for reporting or analytics beyond what you can get through our pre-built reports and the Reports API. We plan to add more data sets to this offering in future.

To find what reporting datasets are available for you, use the GET to /datasets. You can then request information or data for that dataset using the API IDs in the response.

/content Content API

API for accessing Preservica content and displaying on discovery platforms.

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).

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

Searching

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.

You need to set the metadata query parameter, and also put the metadata fields in the q parameter's fields section, if you want metadata in the response. These fields are the custom indexer short name, e.g. xip.created or oai_dc.subject.

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.

Search results can also be generated as a CSV using the /search-export endpoint.

Object Details

The /object-details endpoint takes an object ID (with the sdb:IO or :SO 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": "https://eu.preservica.com/Render/render/external?entity=IO&entityRef=eb660290-fda0-40ae-a878-e82af22ce636",
                "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 you can inspect. Possibly useful are:

sdbcmis:parentId and sdbcmis:parentName, if you are accessing an object without that context and you want to show it.
sdbcmis:downloadable to see if the current user has permission to download the item. If they do, cmis:contentStreamLength and cmis:contentStreamMimeType will tell you more about the content and cmis:contentStreamFileName is a potential downloadable name.

Content

You can retrieve content for an asset through the /download endpoint. This will fetch the displayable content for the asset (the same thing that is rendered in UA when you visit the asset). It accepts ranged requests so you can use it to back e.g. a video player. If you want more specific bits of content inside the asset, use the Entity API.

/entitlement Entitlement API

API for entitlement details.

This API allows you to manage and view entitlement data. Management actions require Admin permissions, i.e. on cloud hosted systems they are only available to Preservica staff or automated processes.

Edition

The edition of a tenant provides access to features (returned via /api/admin/features) without setting system properties explicitly. Use these endpoints to discover which edition you are on (for example to show different UI elements), or update it to move a tenant onto a different edition.

/entity Entity API

API for content read and write - to retrieve and update information about entities within the Preservica data store.

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). Most responses include an <AdditionalInformation> element with links to related resources.

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="http://preservica.com/EntityAPI/v8.1" xmlns:xip="http://preservica.com/XIP/v8.1">
    <Children>
        <Child title="Library Collection" ref="c322f2c3-8f70-41ad-beb8-3506eac9fd23" type="SO">https://leven.int.preservica.com/api/entity/structural-objects/c322f2c3-8f70-41ad-beb8-3506eac9fd23</Child>
        <Child title="Audio Recordings" ref="71143bfd-b29f-4548-871c-8334f2d2bcb8" type="SO">https://leven.int.preservica.com/api/entity/structural-objects/71143bfd-b29f-4548-871c-8334f2d2bcb8</Child>
        <Child title="Thomas Telford Exhibition" ref="1822b429-e792-4221-bfb3-86d754ad5249" type="SO">https://leven.int.preservica.com/api/entity/structural-objects/1822b429-e792-4221-bfb3-86d754ad5249</Child>
    </Children>
    <Paging>
        <Next>https://leven.int.preservica.com/api/entity/root/children?max=3&amp;start=3</Next>
        <TotalResults>5</TotalResults>
    </Paging>
    <AdditionalInformation>
        <Self>https://leven.int.preservica.com/api/entity/root/children?max=3</Self>
    </AdditionalInformation>
</ChildrenResponse>

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="http://preservica.com/EntityAPI/v8.1" xmlns:xip="http://preservica.com/XIP/v8.1">
    <xip:InformationObject>
        <xip:Ref>a9e1cae8-ea06-4157-8dd4-82d0525b031c</xip:Ref>
        <xip:Title>filey_brigg</xip:Title>
        <xip:Description>An image of Filey Brigg</xip:Description>
        <xip:SecurityTag>open</xip:SecurityTag>
        <xip:Parent>866d4c6e-ee51-467a-b7a3-e4b65709cf95</xip:Parent>
    </xip:InformationObject>
    <AdditionalInformation>
        <Self>https://leven.int.preservica.com/api/entity/information-objects/a9e1cae8-ea06-4157-8dd4-82d0525b031c</Self>
        <Parent>https://leven.int.preservica.com/api/entity/structural-objects/866d4c6e-ee51-467a-b7a3-e4b65709cf95</Parent>
        <Links>https://leven.int.preservica.com/api/entity/information-objects/a9e1cae8-ea06-4157-8dd4-82d0525b031c/links</Links>
        <Identifiers>https://leven.int.preservica.com/api/entity/information-objects/a9e1cae8-ea06-4157-8dd4-82d0525b031c/identifiers</Identifiers>
        <EventActions>https://leven.int.preservica.com/api/entity/information-objects/a9e1cae8-ea06-4157-8dd4-82d0525b031c/event-actions</EventActions>
        <Metadata>
            <Fragment schema="http://preservica.com/schema/sample/v1.0">https://leven.int.preservica.com/api/entity/information-objects/a9e1cae8-ea06-4157-8dd4-82d0525b031c/metadata/dda13399-a6c1-420e-8d47-458062c43209</Fragment>
        </Metadata>
        <Representations>https://leven.int.preservica.com/api/entity/information-objects/a9e1cae8-ea06-4157-8dd4-82d0525b031c/representations</Representations>
    </AdditionalInformation>
</EntityResponse>

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

Entities

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).

Uploading or Referencing New Content

There are also some endpoints that allow you to upload new content, or tell Preservica to fetch new content from a configured location. All of these will return a progress token (see Long Running Tasks below) which you can use to track the action. The main ways are:

POST to an SO or to /root to upload a package for ingest. This is equivalent to running the Standard Ingest workflow in that folder, and selecting the package file that you upload.
The same as above, but using the upload-file endpoint on an SO or /root to upload a single file for ingest.
Tell Preservica to start an ingest from a file in a source location (see Location API), either within an SO or under /root.

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). Every POST request under /actions is like this. 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, in which case the progress token might be the API ID of a monitor which you can compare to the response of /monitors.

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.

/location Location API

API for interacting with locations (aka sources)

This API provides information about locations (also known as sources) configured in Preservica. Currently it only offers information about upload locations (i.e. ingest sources). Use this API if you need to upload content into Preservica which is too large or inconvenient to send to ingest endpoints on the Entity API. You'll need to use the temporary upload credentials to upload content into the location.

/metadata Metadata API

API for retrieving and updating metadata configuration.

This API allows you to manage the new view (Forms and Groups) of descriptive metadata. There are endpoints under /forms to manage metadata forms, which are the way to define how descriptive metadata should be viewed and edited in a UI, and /groups to manage metadata groups, which let you define some descriptive metadata without specifying an XML schema.

/par PAR API

API for retrieving and updating business rules, preservation actions etc from a Preservation Action Registries (PAR) compliant endpoint.

This API is for getting information from the Preservica Registry, and updating it if you have institution specific preservation needs. Access to read the Registry is generally open. Typical use cases involve reading information off entities (generation and representation formats) and reading them from /file-formats or /representation-formats to display names to a user, or reading a list of migration rules from /business-rules to offer migration options to a user.

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.

/process Process API

API for starting processes, and retrieving and updating configuration for processes.

The Process API lets you see information about process (currently only Ingest) configuration and run processes using these configurations. It also allows updating and create new configurations.

/processmonitor Process Monitoring API

API for retrieving and updating monitoring information about processes.

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. You can also see some background system actions (in particular, automatic recharacterisation or migration policy application) and other user triggered actions (like Move operations) in this data. This API exposes the same information available through the Monitor webapp, or the Notifications panel on SDB and Explorer, if you have those enabled.

If a process runs over multiple days and is updating the size values as it does so, you can get a daily history of those numbers from the timeseries endpoint.

Completed processes will be removed from this data 90 days after completion.

/remote-contributors Remote contributors API

Remote contributors API.

This API allows you to manage Invitations and Submissions for our External Submissions process programmatically. See the UI-driven guide for the feature, as the API covers the same use cases.

/report Report API

API to list available reports, send requests for reports and download them.

The Report API allows you to retrieve and run reports. Like the Entity API (see Long Running Processes), it has a progress endpoint to allow you to track long running reports, and an /actions/reports endpoint to see running or completed reports.

Note that this API is about generation of the document style reports (normally PDF), i.e. what you get from the Reports item in the main application. If you want data to show in an interactive way or to analyse outside Preservica, you might want the Analytics API.

/reference-metadata Reference Metadata API

API for retrieving reference metadata.

This API allows you to view, update and manage reference metadata (the same data that is available through Data Management > Reference Metadata in the UI). Endpoints under /records manage data within tables, and endpoints under /tables manage the tables themselves.

/security Security API

API for retrieving and updating information in the Preservica security model.

This API provides security information visible for the current user. This is a list of tags that the current user can see, and what permissions they have on those tags. Use this information in conjunction with security descriptor information on entities to decide what actions to show a user, or to determine which tags should be offered when creating entities etc.

Security configuration is done through the /security section of the Admin API.

/settings Settings API

API for retrieving information about configuration settings.

This API allows the retrieval and update of information about settings on your Preservica system.

Profiles and Rules

A common pattern within settings is that a policy is based on a collection of profiles ("what to do") and rules ("where to do it").

Profiles are a set of actions that can be applied to content. Profiles for each type of settings have different options; see the examples on the endpoint documentation for details.

Rules define which profile gets used for content. For any piece of content (for migration policy, this applies to content objects), each rule is evaluated, and the first one that matches will be applied. The selectors inside selectorSettings have the same meaning as the fields by the checkboxes in the UI.

Migration Settings

This is equivalent to the Preservation page in the UI; use the endpoints under /migration/config/profiles to configure the profiles, and /migration/config/rules to set up rules.

Migration profiles are based around file formats and business rules, either as part of a rule set or as format specific selections. These objects are all PAR entities and you can get more information (for example, to get a friendly display name) from the PAR API. Retrieving a migration profile will also include some of this in a parInformation property, allowing you to show a summary without making extra requests.

If you have auto-preservation turned on, making changes to profiles or rules (including reordering rules) will trigger a background evaluation of assets that need changing as a result of the policy change. These changes will be aggregated over a short period like they are through the UI. But if you're going to be making a lot of changes, consider turning auto-migration off (or to IngestOnly) first, and turning it back on (which will trigger a re-evaluation) when you're done. Alternatively, aggregate all your changes together and submit an entire new policy.

Metadata Enrichment Settings

These endpoints allow you to set up a metadata enrichment policy, to be applied on ingest. A ME policy has settings for each tool that could potentially be run. Equivalent to the Enrichment page in the UI.

External Sync Settings

These endpoints allow you to set up an external sync policy, to be applied on ingest. This policy is simply whether to sync external content or not. Equivalent to the External Sync page in the UI.

External sync is done by notifying external systems through a webhook, which is triggered for any newly ingested asset that matches your policy. You also need to subscribe to the webhook via the Webhook API.

Ingest Configuration

These endpoints don't follow the profile/rule pattern. Instead, they allow you to set up different configurations for ingest without needing to interact with the Workflow API.

/storage Storage API

API for retrieving storage details.

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

/user User API

API for getting user details and managing users.

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 your profile and sessions. User management is done through the /users section of the Admin API.

A GET to /details will return user information like that in a login response. You can use this if you've used external authentication or asked the user to log in manually, to retrieve information to display about the user (e.g. a name) and adjust UI choices based on the user's roles,

/workflow Workflow API

API for control tasks and workflow administration - to access information about workflows, manage their definitions and contexts as well as control their execution.

This XML 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.

Details of parameters to workflow steps are only available to admin users (on cloud hosted systems, that means Preservica staff) because this can include sensitive information about the system.

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.

/webhook Webhook API

API for getting webhook details and managing webhooks.

With this API a manager can register web hooks to be called by Preservica when particular actions happen within the system. The list of actions you can listen for is limited, but we'll be adding to this capability in future.

To configure a webhook, you need to set your server up to respond to the validation challenge, and then make a request to POST /subscriptions. Preservica will send a validation challenge, and if your endpoints returns as expected, your webhook will be registered. This verifies that the endpoint is correct and the server is accessible from Preservica. (Use the DELETE endpoint to remove a subscription.)

Your endpoint will receive a HTTP POST from Preservica with a notification body every time the action you subscribed to happens. You won't get detailed information about entities or other aspects of Preservica in the notification; you'll have to use other APIs to get the information you need. Your endpoint should return quickly; we recommend you accept the webhook notification and queue up your processing internally within your server (for example posting tasks onto a thread pool executor, or posting messages onto an AMQP queue).

External Integration

APIs for integration with external systems that use defined standards

We support a limited view of what's in Preservica through some open standards. Use these APIs if you need to integrate with a system which uses these protocols. If you have a free choice, we recommend you use the Entity or Content API to access this information.

OAI-PMH

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.

CMIS

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.

API Documentation 8.1