DonCruickshank: Created page with "''This API is for managing an intervention as a single participant. It uses the session cookie for authentication and so JavaScript code will automatically authenticate as the logged in participant. If you need to perform changes to an intervention as a whole (e.g. create users, access user data for any participant, etc.) then see REST API version 1'' TOC = API usage = The API is intended to be used by JavaScript embedded into the intervention pages to manage..."

2025-11-24T15:28:41Z

Created page with "''This API is for managing an intervention as a single participant. It uses the session cookie for authentication and so JavaScript code will automatically authenticate as the logged in participant. If you need to perform changes to an intervention as a whole (e.g. create users, access user data for any participant, etc.) then see REST API version 1'' __TOC__ = API usage = The API is intended to be used by JavaScript embedded into the intervention pages to manage..."

New page

''This API is for managing an intervention as a single participant. It uses the session cookie for authentication and so JavaScript code will automatically authenticate as the logged in participant. If you need to perform changes to an intervention as a whole (e.g. create users, access user data for any participant, etc.) then see [[REST API version 1]]''

__TOC__

= API usage =

The API is intended to be used by JavaScript embedded into the intervention pages to manage aspects of the current participant. For this reason, it uses the same authentication method (cookie-based session identifier) as the regular intervention pages.

The API will not be available if there is no intervention session associated with the browser. The intervention session only starts on the first POST request received from the browser (otherwise, the session data would be overwhelmed by search and AI bot activity). In this case, the API will return a 404 HTTP response.

If the intervention session has started but there is no current participant yet, then the API will return a 401 HTTP response.

= Quick example =

Here is a minimal example using the Fetch API:

{| class="wikitable"
|-
! Code !! Response
|-
| width="50%" valign="top" |
<pre>
async function getUserData() {

const command = {
type: "listUserData",
};

const response = await fetch("/api/v1", {
method: "POST",
body: JSON.stringify(command)
});

return await response.json();
}

// Example call:

const response = await getUserData();
</pre>
| width="50%" valign="top" |
<pre>
{
"data": [
"age",
"gender",
"weight"
],
"status": "ok"
}
</pre>
|}

= Accessing user data =

== List user data ==

API request to list user data. All user data fields are returned without pagination.

{| class="wikitable"
|-
! Request !! Response
|-
| width="50%" valign="top" |
<pre>
{
"type": "listUserData"
}
</pre>
| width="50%" valign="top" |
<pre>
{
"data": [
"age",
"gender",
"weight"
],
"status": "ok"
}
</pre>
|}

== Get user data ==

API request to get user data.

{| class="wikitable"
|-
! Request !! Response
|-
| width="50%" valign="top" |
<pre>
{
"type": "getUserData",
"id": "age"
}
</pre>
| width="50%" valign="top" |
<pre>
{
"data": 25,
"id": "age",
"status": "ok"
}
</pre>
|}

If the user data field does not exist then the response will have a status value of "notFound".

== Set user data ==

API request to create or update user data.

{| class="wikitable"
|-
! Request !! Response
|-
| width="50%" valign="top" |
<pre>
{
"type": "setUserData",
"id": "consent",
"data": true
}
</pre>
| width="50%" valign="top" |
<pre>
{
"id": "consent",
"status": "ok"
}
</pre>
|}

== Delete user data ==

API request to delete user data.

{| class="wikitable"
|-
! Request !! Response
|-
| width="50%" valign="top" |
<pre>
{
"type": "deleteUserData",
"id": "goal1"
}
</pre>
| width="50%" valign="top" |
<pre>
{
"id": "goal1",
"status": "ok"
}
</pre>
|}

If the user data field does not exist then the response will have a status value of "notFound".

= Combining multiple API requests into a single HTTP request =

An array of requests can be provided instead of a single request. In this case, the API will return an
array of responses in the same order as the requests provided.

An example that gets two user data fields.

{| class="wikitable"
|-
! Code !! Response
|-
| width="50%" valign="top" |
<pre>
async function processMultipleRequests() {

const commands = [
{
type: "getUserData",
id: "age",
},
{
type: "getUserData",
id: "consent"
}
];

const response = await fetch("/api/v1", {
method: "POST",
body: JSON.stringify(commands)
});

return await response.json();
}

// Example call:

const response = await processMultipleRequests();
</pre>
| width="50%" valign="top" |
<pre>
[
{
"data": 25,
"id": "age",
"status": "ok"
},
{
"data": true,
"id": "consent",
"status": "ok"
}
]
</pre>
|}

You can mix and match request types, e.g. setting three fields and deleting a fourth field.

Participant API version 1 - Revision history