QSVC-Platform GraphQL API Reference
QSVC-Platform is a framework of services dedicated to resolve many planning use cases using SurgiQ AI based technologies (patented AI algorithms).
The described API expose planning services as GraphQL API. The following service is for scheduling outpatient rehabilitation appointments.
The GraphQL endpoint is online and accessible only by authorized users that need to have KeyCloak authentication in order to create a JWT token to consume the API.
Contact the SurgiQ customer support for obtaining the credentials, the API endpoint and further details. Let's keep in touch.
Terms of Service
API Endpoints
# Online API:
https://api.surgiq.com/graphql
Headers
# GET https://api.surgiq.com/graphql
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5c...How to authenticate
To interact with this API, you need to authenticate via Keycloak. Below are the steps to obtain a token and use it for API requests:
Obtain Authentication Token
Send a POST request to the Keycloak token endpoint:
POST https://api.surgiq.com/realms/test-cliente/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded
Parameters:
- client_id: Your client ID (sent separately).
- client_secret: Your client secret (sent separately).
- grant_type: "client_credentials"
Use the Token for API Requests
Include the obtained token in the Authorization header of your API requests:
Authorization: Bearer {access_token}
Example:
GET https://api.surgiq.com/graphql
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5c...
Example in JavaScript
An example using fetch to authenticate and make an API call is included below:
const fetch = require('node-fetch');
async function authenticateAndFetchData() {
const tokenResponse = await fetch('https://api.surgiq.com/realms/test-cliente/protocol/openid-connect/token, {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: new URLSearchParams({
client_id: 'your-client-id',
client_secret: 'your-client-secret',
grant_type: 'client_credentials'
})
});
const tokenData = await tokenResponse.json();
const accessToken = tokenData.access_token;
const apiResponse = await fetch('http://{API_endpoint}/api/graphql', {
method: 'GET',
headers: {
Authorization: `Bearer ${accessToken}`
}
});
const apiData = await apiResponse.json();
console.log(apiData);
}
authenticateAndFetchData();
Queries
treatmentPackagesPlanning
Response
Returns an OutputData!
Arguments
| Name | Description |
|---|---|
input - InputData!
|
The input structure transmitted to the query. It contains all the configuration data needed by the planning algorithm to perform the elaboration and provide output results. |
Example
Query
query TreatmentPackagesPlanning($input: InputData!) {
treatmentPackagesPlanning(input: $input) {
planningName
planningDate
version
organization {
org
team
}
status {
isLast
isApproved
}
lastUpdate
data
extraData
}
}
Variables
{
"input": {
"data": {
"time": {"dateFrom": "2025-01-13", "dateTo": "2025-03-30"},
"newRegistration": [
{
"idPatient": 61626,
"priority": "2",
"periodicity": 1,
"targetWeek": 0,
"treatmentsTargetDays": [1, 2],
"minWeeklyTreatments": 0,
"maxWeeklyTreatments": 2,
"sameDayWeekTime": false,
"preferredOps": [],
"treatments": [
{
"qualification": "TF",
"idPlace": 71,
"idMachine": null,
"targetStartingTime": "",
"treatmentTotalDuration": 10,
"operatorTotalDuration": 10,
"numOfOperators": 1,
"machineTotalDuration": 0,
"operatorStartAt": 0,
"machineStartAt": 0,
"dayOrder": 0,
"globalOrder": 0,
"idTreatment": 822215
},
{
"qualification": "TF",
"idPlace": 71,
"idMachine": null,
"targetStartingTime": "",
"treatmentTotalDuration": 10,
"operatorTotalDuration": 10,
"numOfOperators": 1,
"machineTotalDuration": 0,
"operatorStartAt": 0,
"machineStartAt": 0,
"dayOrder": 0,
"globalOrder": 1,
"idTreatment": 822216
}
],
"forbiddenDays": []
}
],
"alreadyAssigned": [
{
"machines": [
{"idMachine": -1, "timeStart": "08:40", "timeEnd": "08:40"}
],
"operators": [
{
"idOperator": 40,
"assignedOpNoInstrT": {"timeStart": "08:40", "timeEnd": "08:50"}
}
],
"idAssignment": 822214,
"idPlace": 71,
"idPatient": 61671,
"duration": 10,
"priority": 9,
"date": "2025-01-27",
"time": "08:40"
}
],
"operators": [
{
"idOperator": 40,
"operatorName": "",
"shift": [
{
"timeStart": "09:00",
"timeEnd": "09:15",
"date": "2025-01-13",
"qualifications": ["TF", "N", "O", "AMB"],
"numPatients": 1
},
{
"timeStart": "10:00",
"timeEnd": "12:00",
"date": "2025-01-13",
"qualifications": ["TF", "N", "O", "AMB"],
"numPatients": 1
},
{
"timeStart": "08:40",
"timeEnd": "09:00",
"date": "2025-01-13",
"qualifications": ["TF", "N", "O", "AMB"],
"numPatients": 2
},
{
"timeStart": "09:15",
"timeEnd": "10:00",
"date": "2025-01-13",
"qualifications": ["TF", "N", "O", "AMB"],
"numPatients": 2
},
{
"timeStart": "13:20",
"timeEnd": "15:40",
"date": "2025-01-13",
"qualifications": ["TF", "N", "O", "AMB"],
"numPatients": 1
},
{
"timeStart": "09:00",
"timeEnd": "09:15",
"date": "2025-01-14",
"qualifications": ["TF", "N", "O", "AMB"],
"numPatients": 1
},
{
"timeStart": "10:00",
"timeEnd": "12:00",
"date": "2025-01-14",
"qualifications": ["TF", "N", "O", "AMB"],
"numPatients": 1
},
{
"timeStart": "08:40",
"timeEnd": "09:00",
"date": "2025-01-14",
"qualifications": ["TF", "N", "O", "AMB"],
"numPatients": 2
},
{
"timeStart": "09:15",
"timeEnd": "10:00",
"date": "2025-01-14",
"qualifications": ["TF", "N", "O", "AMB"],
"numPatients": 2
},
{
"timeStart": "13:20",
"timeEnd": "15:40",
"date": "2025-01-14",
"qualifications": ["TF", "N", "O", "AMB"],
"numPatients": 1
}
]
}
],
"opLeaves": [
{"id": 40, "isVacation": true, "date": "2025-02-13", "intervals": []},
{
"id": 34,
"isVacation": false,
"date": "2025-03-17",
"intervals": [{"timeStart": "08:40", "timeEnd": "12:00"}]
}
],
"places": [
{
"idPlace": 71,
"placeName": "",
"infoDay": [
{
"timeStart": "08:10",
"timeEnd": "12:20",
"date": "2025-01-13",
"qualification": ["AMB"],
"numPatients": 12
},
{
"timeStart": "08:10",
"timeEnd": "12:20",
"date": "2025-01-14",
"qualification": ["AMB"],
"numPatients": 12
}
],
"travelingTimeTo": []
}
],
"placeLeaves": [
{"id": 71, "isVacation": true, "date": "2025-02-13", "intervals": []}
],
"machines": [
{
"idMachine": 5,
"machineName": "",
"idPlace": 1,
"infoDay": [
{
"timeStart": "09:00",
"timeEnd": "17:00",
"date": "2025-01-13",
"qualification": ["AMB"],
"numPatients": 3
},
{
"timeStart": "09:00",
"timeEnd": "17:00",
"date": "2025-01-14",
"qualification": ["AMB"],
"numPatients": 3
}
],
"compatibleWith": []
}
],
"machineLeaves": [
{"id": 5, "isVacation": true, "date": "2025-02-13", "intervals": []}
]
},
"source": "Query",
"scope": "NM",
"organization": {"org": "9", "team": 7}
}
}
Response
{
"data": {
"treatmentPackagesPlanning": {
"planningName": "TreatmentPackagesPlanning_61626_efbdaa42-e60e-4659-bce0-d75f99fc4153",
"planningDate": "2025-01-21",
"version": 1,
"organization": {"org": "9", "team": 7},
"status": {"isLast": true, "isApproved": false},
"lastUpdate": "2025-01-21",
"data": [
{
"idAssignment": 822215,
"idPlace": 71,
"idPatient": 61626,
"duration": 10,
"priority": "2",
"date": "2025-01-13",
"time": "08:40",
"machines": [
{"idMachine": -1, "timeStart": "08:40", "timeEnd": "08:40"}
],
"operators": [
{
"idOperator": 40,
"assignedOpNoInstrT": {"timeStart": "08:40", "timeEnd": "08:50"}
}
]
},
{
"idAssignment": 822216,
"idPlace": 71,
"idPatient": 61626,
"duration": 10,
"priority": "2",
"date": "2025-01-14",
"time": "08:40",
"machines": [
{"idMachine": -1, "timeStart": "08:40", "timeEnd": "08:40"}
],
"operators": [
{
"idOperator": 40,
"assignedOpNoInstrT": {"timeStart": "08:40", "timeEnd": "08:50"}
}
]
}
],
"extraData": {
"time": [],
"newRegistration": [
{
"preferredOps": [40],
"treatmentsTargetDays": [1, 2],
"treatments": []
}
],
"alreadyAssigned": []
}
}
}
}
Types
Boolean
Description
The Boolean scalar type represents true or false.
InputData
Description
The input structure transmitted to the query. It contains all the configuration data needed by the planning algorithm to perform the elaboration and provide output results.
Fields
| Input Field | Description |
|---|---|
source - Sources!
|
Specifies the origin of the input data. |
scope - Scopes!
|
These are the areas that are generally implemented to treat rehabilitation patients. |
organization - OrganizationInput!
|
The hospital facility where rehabilitation treatments are carried out. |
data - JSON!
|
Planning data, including places, patients, operators, etc... |
Example
{
"source": "DB",
"scope": "NM",
"organization": OrganizationInput,
"data": {}
}
Int
Description
The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.
Example
987
JSON
Description
The JSON scalar type represents JSON values as specified by ECMA-404.
Example
{}
OrganizationInput
OrganizationOutput
OutputData
Description
Object containing the data elaborated by the AI engine and other details.
Fields
| Field Name | Description |
|---|---|
planningName - String!
|
The planning name given by the user. |
planningDate - String!
|
The planning date. |
version - Int!
|
The version assigned to the planning. A planning with same name and date can have multiple versions. |
organization - OrganizationOutput!
|
The hospital facility where rehabilitation treatments are carried out. |
status - Status
|
The planning status. |
lastUpdate - String!
|
The date that the planning was last updated. |
data - JSON!
|
The output of the planning elaboration. |
extraData - JSON
|
The extra data associated with the data planned, if available. |
Example
{
"planningName": "TreatmentPackagesPlanning_61626_efbdaa42-e60e-4659-bce0-d75f99fc4153",
"planningDate": "2025-01-21",
"version": 1,
"organization": {"org": "9", "team": 7},
"status": {"isLast": true, "isApproved": false},
"lastUpdate": "2025-01-21",
"data": [
{
"idAssignment": 822215,
"idPlace": 71,
"idPatient": 61626,
"duration": 10,
"priority": "2",
"date": "2025-01-13",
"time": "08:40",
"machines": [{"idMachine": -1, "timeStart": "08:40", "timeEnd": "08:40"}],
"operators": [
{
"idOperator": 40,
"assignedOpNoInstrT": {"timeStart": "08:40", "timeEnd": "08:50"}
}
]
},
{
"idAssignment": 822216,
"idPlace": 71,
"idPatient": 61626,
"duration": 10,
"priority": "2",
"date": "2025-01-14",
"time": "08:40",
"machines": [{"idMachine": -1, "timeStart": "08:40", "timeEnd": "08:40"}],
"operators": [
{
"idOperator": 40,
"assignedOpNoInstrT": {"timeStart": "08:40", "timeEnd": "08:50"}
}
]
}
],
"extraData": {
"time": [],
"newRegistration": [
{"preferredOps": [40], "treatmentsTargetDays": [1, 2], "treatments": []}
],
"alreadyAssigned": []
}
}
Scopes
Description
The areas that are generally implemented to treat rehabilitation patients.
Values
| Enum Value | Description |
|---|---|
|
|
Neurological and orthopedic rehabilitation. |
|
|
Cardiac and respiratory rehabilitation. |
|
|
Both types of rehabilitation patients. |
Example
"NM"
Sources
Description
The origin of the input data.
Values
| Enum Value | Description |
|---|---|
|
|
The input data comes from the database. |
|
|
The input data comes from the client. |
|
|
The input data comes from an external source. |
Example
"DB"
Status
String
Description
The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.
Example
"xyz789"