How does the Researcher Solutions (Haplo) REST API work?

Data format

REST APIs are provided to access and modify objects and data in Researcher Solutions applications. The APIs use JSON formatted requests and responses and are accessed via HTTPS.

Authentication

An API key is used to authenticate as a user of the system, and gives the external system the same permissions as that user. Multiple API keys can be generated for a single application to provide external systems with differing levels of access.

A set of Service Users are provided with the application and can be found in 

System Management → Users → SRV

The application comes pre-configured with the following REST API Service Users:

• API v0: File
• API v0: Object
• API v0: User

Navigate to any of the above users to create a new API key. Note: You can also create API keys on regular users. 

When creating a new API Key, use the /api/v0- request path to restrict the API key to all REST APIs.

Note: When you are ready to make your first API call, the username is always haplo (regardless of which user the API key was created for).

Endpoints

Endpoints are relative to the system base URL. For example, if the system URL used by the service is https://app.example.org then given the endpoint /api/example the URL https://app.example.org/api/example should be requested.

Response

Every request to the API will receive a response in JSON format with the following structure

• success
• kind

kind contains a code that defines where the response is coming from. In addition to the kinds provided by each API implementation, there are the following generic kinds:

success can have a value of true or false, and tells you whether the request succeeded or failed. If the request succeeded, more data defined by the specific API you are using can be expected to be included in the response.

Authentication

Before you can do anything, you need an API Key. This acts as your password.

Step A: Get your Key (example)

1. Log into your application as an Administrator.
2. Go to System Management > Users > SRV (Service Users).
3. Select the relevant service user (e.g., API v0: Object).
4. Click the New API key at the end of the page, give it a name, and copy the key immediately (you won't be able to see it again!).

By default, the Service User API v0: Object can access all endpoints provided by that API for all the objects in the application. Similarly, Service Users API v0: File and API v0: User can access all Files and Users in the application respectively.

API keys are not restricted to the Service Users. You may create a dedicated API User (in the Users → ACTIVE menu). Here, you can add Group Membership(s) on the user (API v0: File and/or, API v0: Object and/or API v0: User) and create an API key for accessing the selected APIs.

Example: You would like to create a dedicated API User who can access all three REST APIs:

1. Create the new user in System Management
2. Add the three API groups to the newly created user’s Group Membership
3. Create the new API key with “Request path” set to /api/v0-
   1. This path grants access to all three REST API endpoints (i.e. v0-object, v0-file, v0-user)

Step B: Authenticate with the API

The API uses HTTP Basic Auth:

• Username: The username is always haplo
• Password: The API Key created in Step A

Example Header: If your API key is ABC123XYZ, your authentication header would be the base64 encoded version of haplo:ABC123XYZ.

Tip: If you use a tool like Postman or curl, simply select "Basic Auth", type haplo as the username, and paste your API key as the password. The tool handles the encoding for you.

Core Concept: The "Ref"

Almost everything returned from the API (e.g. a document, a project, a person) is an Object. Every object has a unique ID called a Ref.

• It looks like a random string of characters (e.g., 83w92).
• You will use this Ref whenever you want to point to a specific record.

Users API

Full documentation available at https://docs.haplo.org/rest-api/users 

Note for on-platform customers: The Cayuse Platform manages user information through its own set of APIs (e.g. HR Connect and the Public API). Therefore, while retrieving user data via the Users API (using GET requests) is acceptable, modifying this data (using POST requests) should be avoided.

Example - Finding a User by Username

Goal: You want to find the profile details of a user with the username jsmith.

The Endpoint: GET /api/v0-user/find-by-tag

The Request: You must include the tag you are looking for as a query parameter. For a username, the parameter is tag:username.

GET https://{your-app}.cayuse.com/api/v0-user/find-by-tag?tag:username=jsmith

Authorization: Basic (haplo:YOUR_API_KEY)

The Response (Simplified):

{
    "success": true,
    "kind": "haplo:api-v0:user:find-by-tag",
    "users": [
        "130"
    ]
}

Result: The API tells you the internal ID (130) for jsmith. You can now use that ID to fetch their full profile (using endpoint GET /api/v0-user/id/130).

Objects API

Full documentation available at https://docs.haplo.org/rest-api/objects 

The basic object information is augmented by “sources” of additional information, for example, workflows and documents around the object. When requesting an object, you specify which sources you need included in the response. 

Example - Fetching a Specific Record

Goal: You have a Project with the Ref 83w92 and you want to read its title and details.

The Endpoint: GET /api/v0-object/ref/[Ref]

The Request:

GET https://{your-app}.cayuse.com/api/v0-object/ref/83w92

Authorization: Basic (haplo:YOUR_API_KEY)

The Response (Simplified):

{
    "kind": "haplo:object:0",
    "ref": "83w92",
    "title": "Research Project Alpha",
    "creationDate": "2023-01-14T17:05:18Z",
    "attributes": [
        {
         ...
        }
    ]
}

Files API

Full documentation available at https://docs.haplo.org/rest-api/files 

The Files REST API provides endpoints to access files in the application.

Example - Fetching a Specific File

Goal: Your previous query on Object 83w92 included a file digest in the documents object of the response (simplified example):

"document": [
    {
        "digest": "3d359503bf813d55f2ca4aa...",
        "filename": "Important file.pdf"
    }
]

To download this file using the Files API, you will use the /api/v0-file/metadata endpoint:

The Request:

GET https://{your-app}.cayuse.com/api/v0-file/metadata/3d359503bf813d55f2ca4aa... 

Authorization: Basic (haplo:YOUR_API_KEY)

The Response (Simplified):

{
    "success": true,
    "kind": "haplo:api-v0:file:metadata",
    "file": {
        "digest": "3d359503bf813d55f2ca4aa...",
        "mimeType": "application/pdf",
        "filename": "Important file.pdf",
        ...
    }
   "download": {
        "url": "https://{your-app}.cayuse.com/file/3d359503bf813d55f2ca4aa.../11747/Important%20file.pdf?s=120f04280b7f2703e90a6b35ce50ec4c06efd64c32799e99babef108734a7a1b,1768790549,1768804949",
        "validUntil": "2026-01-19T06:42:13.842Z"
    }
}

In the above example, the url includes the direct download path to your document. 

validUntil specifies the life-time of the URL (~4 hours).