1. Introduction

The OASIS REST API provides access to information about OASIS Projects via a RESTful API.

It is designed to provide programmatic access to OASIS Project information and its output is very similar to that of the existing "Export" function that can be found on the OASIS Projects list.

The base URL for the OASIS REST API is https://api.oasis.ac.uk/v1/

2. Authentication

To authenticate with the OASIS REST API, send an Authorization: Basic HTTP header with each request, containing a Base64 encoded email and password pair, separated by a semicolon. All API requests require authentication.

3. Projects Endpoint

You can request information about OASIS Projects using the https://api.oasis.ac.uk/v1/projects endpoint.

Specifying an OASIS Project ID e.g. https://api.oasis.ac.uk/v1/projects/oasis-project-123 will return information about that specific Project.

If you do not provide an OASIS Project ID then you must provide additional org_id and role parameters - the API will then return 10 projects per page by default, with the page number specified by the page parameter. You can instead, return anywhere from 1 to 1,000 projects per page by specifying the results_per_page parameter.

e.g. https://api.oasis.ac.uk/v1/projects?org_id=1000001&role=O1&page=1&results_per_page=20

Filtering Projects

You can provide the reviewer_id parameter to filter the results by reviewer ID.

You can filter the results by the date records were created and/or last updated by providing the date_created_min, date_created_max, date_last_updated_min and date_last_updated_max parameters respectively, in YYYY-MM-DD format.

4. Other Endpoints

A list of your organisations and their respective IDs can be obtained by making a request to https://api.oasis.ac.uk/v1/organisations

A list of valid roles and reviewer IDs for an organisation can by obtained by making a request to
https://api.oasis.ac.uk/v1/reviewers/[organisation_id]

Roles are listed below.

Please note:

  • Roles begin with the letter 'O' not the number '0'.
  • Not every organisation has access to every role.
Role Description
O1 Researcher which submits OASIS forms (commercial data inputter)
O1a Community group which submits OASIS forms
O2 Historic Environment Record (regional reviewer)
O2a Other reviewing organisation
O3 Museum/Archive
O4 Organisation with responsibility for reviewing OASIS records nationally
O4a Discovery and Excavation in Scotland
O5 Organisation which needs to download completed OASIS records for analysis

5. Code Example

Below is a (server-side) JavaScript code example using Fetch.

const email = 'your@email.ac.uk';
const password = 'yourPassword';
const encodedPair = Buffer.from(`${email}:${password}`).toString('base64');

fetch('https://api.oasis.ac.uk/v1/projects/oasis-project-123', {
    headers: {
         Authorization: `Basic ${encodedPair}`) 
    }
})
.then(res => res.json())
.then(json => console.log(json));
API requests made from client-side JavaScript code will fail due to same-origin policy. This is to help avoid the exposure of user credentials in client-side code.

University of York Legal Statements