Web API

SliceVault provides a REST-style Web API for common trial operations such as listing trials, reading patient and visit data, downloading images, exporting reports, exporting audit logs, creating patients, creating visits, uploading images, and updating visit status.

This page is a practical guide. For the full endpoint list, request parameters, and response schema, use the built-in Swagger page at /swagger. The Swagger page is available to authenticated users with the API role.

What the API can be used for

Common use cases include:

list trials available to the authenticated API user
list patients and visits in a trial
get image set IDs and series IDs for download
read forms, checklist data, and queries
create patients
create visits
upload image data to an existing patient and visit
update visit status
download image sets and series
generate and download reports
export audit logs

For most integrations, the practical starting point is:

authenticate
find the trial
find or create the patient
find or create the visit
upload or download data
optionally update visit status or export reports

Base URL

All endpoints are available below:

https://yourdomain.slicevault.com/WebApi/

Example:

https://us.slicevault.com/WebApi/GetTrialNames

Roles and access

SliceVault separates read access from write access.

Role	Typical use
`webAPI`	Read trial, patient, visit, form, checklist, query, report, image, and audit-log data
`webAPIWriter`	Create or update data through the API, including patient creation, visit creation, uploads, and visit-status changes

Notes:

Users only see data for trials they are assigned to.
401 Unauthorized usually means the credentials or token are invalid, or the user does not have the required API role.
403 Forbidden usually means the credentials are valid, but the user does not have access to the requested trial or item.
Trial-specific write actions should be done with webAPIWriter.

Authentication

SliceVault supports two main authentication patterns:

Basic authentication with username and password
API token exchange to short-lived JWT Bearer tokens

The recommended approach for integrations is API token plus JWT.

Recommended token flow

Login to SliceVault with a user that has the webAPI or webAPIWriter role.
Open Settings and create an API token.
Exchange that token through ExchangeToken.
Use the returned JWT in the Authorization: Bearer header.

Example:

curl -X POST "https://us.slicevault.com/WebApi/ExchangeToken" \
  -H "Authorization: Bearer svt_your_api_token"

Typical response:

{
  "token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "expires_at": "2026-05-01T12:34:56Z"
}

Then use that JWT in later requests:

curl "https://us.slicevault.com/WebApi/GetTrialNames" \
  -H "Authorization: Bearer eyJhbGciOi..."

Basic authentication example

Basic authentication is still useful for quick testing:

curl "https://us.slicevault.com/WebApi/GetTrialNames" \
  -u "api.user@example.com:your_password"

Common patterns

GET endpoints

Read-only endpoints usually use query-string parameters:

GET /WebApi/GetPatientsFromTrial?trial=<trial_name>

POST endpoints with JSON

Write endpoints usually use JSON request bodies:

POST /WebApi/CreatePatientInTrial
Content-Type: application/json

POST endpoints with background jobs

Some operations prepare a downloadable file or perform server-side processing. These return a backgroundJobID and sometimes a transmitID.

Typical flow:

Call the prepare endpoint
Poll GetBackgroundJobStatus?backgroundJobID=...
Download the result using the returned transmitID

Multipart upload

Image upload uses multipart/form-data with a file and additional fields such as patientID and visitName.

Main use cases

These are the most common operational flows. Swagger remains the main reference for the full API surface.

1. List trials available to the API user

Endpoint:

GET /WebApi/GetTrialNames

Example:

curl "https://us.slicevault.com/WebApi/GetTrialNames" \
  -H "Authorization: Bearer <jwt>"

This returns the trials visible to the authenticated user.

2. List patients in a trial

Endpoint:

GET /WebApi/GetPatientsFromTrial?trial=<trial_name>

Example:

curl "https://us.slicevault.com/WebApi/GetPatientsFromTrial?trial=MY_TRIAL" \
  -H "Authorization: Bearer <jwt>"

Use this when you need the SliceVault patient IDs for a trial.

3. List configured visit names for a trial

Endpoint:

GET /WebApi/GetVisitNamesFromTrial?trial=<trial_name>

Example:

curl "https://us.slicevault.com/WebApi/GetVisitNamesFromTrial?trial=MY_TRIAL" \
  -H "Authorization: Bearer <jwt>"

This returns configured visit names and translated labels such as Visit 1, Visit 2, and so on.

4. Create a patient

Endpoint:

POST /WebApi/CreatePatientInTrial

Role:

webAPIWriter

Body:

{
  "trial": "MY_TRIAL",
  "centerID": 123,
  "patientName": "01-999"
}

Example:

curl -X POST "https://us.slicevault.com/WebApi/CreatePatientInTrial" \
  -H "Authorization: Bearer <writer_jwt>" \
  -H "Content-Type: application/json" \
  -d "{\"trial\":\"MY_TRIAL\",\"centerID\":123,\"patientName\":\"01-999\"}"

Use this when your site or integration needs to register a patient before upload.

5. Create a visit for an existing patient

Endpoint:

POST /WebApi/CreateVisitFromPatientIDAndVisitName

Role:

webAPIWriter

Body:

{
  "patientID": 456,
  "visitName": "visit_c"
}

Example:

curl -X POST "https://us.slicevault.com/WebApi/CreateVisitFromPatientIDAndVisitName" \
  -H "Authorization: Bearer <writer_jwt>" \
  -H "Content-Type: application/json" \
  -d "{\"patientID\":456,\"visitName\":\"visit_c\"}"

Use this when the patient already exists and the integration needs to open the next visit.

6. Upload images to a patient and visit

Endpoint:

POST /WebApi/UploadFileToPatientIDAndVisitName

Role:

webAPIWriter

Required fields:

file
patientID
visitName

Optional field:

raw=true

Example:

curl -X POST "https://us.slicevault.com/WebApi/UploadFileToPatientIDAndVisitName" \
  -H "Authorization: Bearer <writer_jwt>" \
  -F "file=@/path/to/upload.zip" \
  -F "patientID=456" \
  -F "visitName=visit_b"

Typical response:

{
  "status": "OK",
  "backgroundJobID": 98765
}

Poll the job until completion:

curl "https://us.slicevault.com/WebApi/GetBackgroundJobStatus?backgroundJobID=98765" \
  -H "Authorization: Bearer <writer_jwt>"

Use this for automated inbound image uploads.

7. Update visit status

Endpoint:

POST /WebApi/UpdateVisitStatus

Role:

webAPIWriter

Body:

{
  "visitID": 789,
  "statusID": 2,
  "reason": "Changed visit status via API"
}

Example:

curl -X POST "https://us.slicevault.com/WebApi/UpdateVisitStatus" \
  -H "Authorization: Bearer <writer_jwt>" \
  -H "Content-Type: application/json" \
  -d "{\"visitID\":789,\"statusID\":2,\"reason\":\"Changed visit status via API\"}"

Use this only when the workflow should be changed programmatically and the reason should be recorded in the audit trail.

8. Download images from a visit

This is usually a 4-step flow.

Step 1: Find the image set

Endpoint:

GET /WebApi/GetImageSetIDsFromPatientIDAndVisitName?patientID=<patient_id>&visitName=<visit_name>

Example:

curl "https://us.slicevault.com/WebApi/GetImageSetIDsFromPatientIDAndVisitName?patientID=456&visitName=visit_a" \
  -H "Authorization: Bearer <jwt>"

Step 2: Prepare the download

Endpoint:

POST /WebApi/PrepareDownloadImageSet

Body:

{
  "imageSetID": 12345
}

Example:

curl -X POST "https://us.slicevault.com/WebApi/PrepareDownloadImageSet" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d "{\"imageSetID\":12345}"

Typical response:

{
  "backgroundJobID": 98765,
  "transmitID": "abc123"
}

Step 3: Poll the background job

curl "https://us.slicevault.com/WebApi/GetBackgroundJobStatus?backgroundJobID=98765" \
  -H "Authorization: Bearer <jwt>"

Wait until completed is true.

Step 4: Download the file

Endpoint:

GET /WebApi/DownloadImageSet?transmitID=<transmit_id>

Example:

curl "https://us.slicevault.com/WebApi/DownloadImageSet?transmitID=abc123" \
  -H "Authorization: Bearer <jwt>" \
  -o imageset.zip

This is the main download flow for full visit image data.

9. Download one series

If you only need one series:

Call GetSeriesIDsFromImageSetID?imageSetID=...
Optionally inspect the series with GetSeriesFromSeriesID?seriesID=...
Download with DownloadSeries?seriesID=...

Example:

curl "https://us.slicevault.com/WebApi/DownloadSeries?seriesID=555" \
  -H "Authorization: Bearer <jwt>" \
  -o series.zip

10. Export forms, checklists, and queries

These endpoints are useful when you need a structured extract of operational data for a visit.

Need	Endpoint
Get visit list for a patient	`GetVisitNamesFromPatientID`
Get forms on a visit	`GetFormsFromVisitID`
Get values from a form	`GetFormContentsFromFormID`
Get QC checklist content	`GetCheckListsFromPatientIDAndVisitName`
Get queries/comments	`GetCommentsFromPatientIDAndVisitName`

Example:

curl "https://us.slicevault.com/WebApi/GetFormsFromVisitID?visitID=789" \
  -H "Authorization: Bearer <jwt>"

11. Export a trial report

There are two patterns:

Generate a report with UpdateReport
Download a report with DownloadReport

Example report generation:

curl -X POST "https://us.slicevault.com/WebApi/UpdateReport" \
  -H "Authorization: Bearer <writer_jwt>" \
  -H "Content-Type: application/json" \
  -d "{\"trial\":\"MY_TRIAL\",\"reportType\":\"CSVImageStatusHistory\"}"

Example direct download:

curl "https://us.slicevault.com/WebApi/DownloadReport?trial=MY_TRIAL&reportType=CSVImageStatusHistory" \
  -H "Authorization: Bearer <jwt>" \
  -o CSVImageStatusHistory.csv

12. Export the audit log

For a direct CSV response:

curl "https://us.slicevault.com/WebApi/GetAuditLogFromTrial?trial=MY_TRIAL" \
  -H "Authorization: Bearer <jwt>" \
  -o AuditLog.csv

The endpoint also supports date filtering:

GET /WebApi/GetAuditLogFromTrial?trial=<trial_name>&fromDate=YYYY-MM-DD&toDate=YYYY-MM-DD

For large exports, use the prepare/download flow:

PrepareDownloadAuditLogFromTrial
GetBackgroundJobStatus
DownloadAuditLogFromTrial

Example:

curl -X POST "https://us.slicevault.com/WebApi/PrepareDownloadAuditLogFromTrial" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d "{\"trial\":\"MY_TRIAL\"}"

Then download with:

curl "https://us.slicevault.com/WebApi/DownloadAuditLogFromTrial?transmitID=<transmit_id>" \
  -H "Authorization: Bearer <jwt>" \
  -o AuditLog.csv

Endpoint groups

Area	Endpoints
Trial and patient discovery	`GetTrialNames`, `GetPatientsFromTrial`, `GetTrialsInfo`, `GetAvailableCenters`
Visit discovery	`GetVisitNamesFromTrial`, `GetVisitNamesFromPatientID`
Visit content	`GetFormsFromVisitID`, `GetFormContentsFromFormID`, `GetCheckListsFromPatientIDAndVisitName`, `GetCommentsFromPatientIDAndVisitName`
Create or update	`CreatePatientInTrial`, `CreateVisitFromPatientIDAndVisitName`, `UploadFileToPatientIDAndVisitName`, `UpdateVisitStatus`
Images	`GetImageSetIDsFromPatientIDAndVisitName`, `PrepareDownloadImageSet`, `DownloadImageSet`, `GetSeriesIDsFromImageSetID`, `GetSeriesFromSeriesID`, `DownloadSeries`
Reports and audit	`UpdateReport`, `DownloadReport`, `GetAuditLogFromTrial`, `PrepareDownloadAuditLogFromTrial`, `DownloadAuditLogFromTrial`

Additional endpoints are also available in Swagger, including supporting read endpoints such as:

GetIsEnrolledFromPatientID
GetVisitNamesFromPatientID
GetFormsFromVisitID
GetFormContentsFromFormID
GetCheckListsFromPatientIDAndVisitName
GetCommentsFromPatientIDAndVisitName

Good practice

Prefer API token plus JWT for integrations.
Use webAPIWriter only where data changes are required.
Poll background jobs before attempting file download.
Treat visit-status changes as controlled workflow actions and always provide a meaningful reason.
Store returned IDs such as patientID, visitID, imageSetID, seriesID, backgroundJobID, and transmitID in your integration flow.
Expect both 401 and 403 responses and handle them separately.

Need more information?

Use /swagger for the live endpoint documentation in your environment.

If you need help with a specific integration, endpoint, request body, or workflow, contact SliceVault support with:

the endpoint name
the trial workflow you want to support
whether your use case is read-only or write-enabled
example input and expected output

This helps us give you the most relevant guidance quickly.

Web API

What the API can be used for

Base URL

Roles and access

Authentication

Recommended token flow

Basic authentication example

Common patterns

GET endpoints

POST endpoints with JSON

POST endpoints with background jobs

Multipart upload

Main use cases

1. List trials available to the API user

2. List patients in a trial

3. List configured visit names for a trial

4. Create a patient

5. Create a visit for an existing patient

6. Upload images to a patient and visit

7. Update visit status

8. Download images from a visit

Step 1: Find the image set

Step 2: Prepare the download

Step 3: Poll the background job

Step 4: Download the file

9. Download one series

10. Export forms, checklists, and queries

11. Export a trial report

12. Export the audit log

Endpoint groups

Good practice

Related pages

Need more information?