Skip to Content
This documentation is provided with the HEAT environment and is relevant for this HEAT instance only.
APIV2HEAT v2 API Documentation

HEAT v2 API Documentation

This document provides detailed information about the available endpoints in the v2 API.
It is intended for developers integrating with the service.
Please note that both the endpoint naming conventions and the response structures are subject to change.

The purpose of this documentation is to outline the current design and provide guidance on expected functionality, while ensuring flexibility as we refine the API to best support all of our clients.

🔐 Authentication & Authorization

Access to all API endpoints requires a valid opaque token.
This token must be included in the Authorization header of each request:

Authorization: Bearer <opaque_token>

The token is mapped to the authenticated user’s role (e.g., Admin, Trainee, Instructor) and determines whether the user has access to a specific route.

If the token is missing, invalid, expired, or lacks required permissions, the request will be rejected with a 401 Unauthorized response.

To Obtain a Token

A client must authenticate against HEAT Auth, our dedicated authentication service.
During this process, users provide their credentials (username and password), and upon successful authentication, the service issues an opaque token.

Example 401 Response

{
  "status": "error",
  "message": "Unauthorized. Please log in to access user data."
}

1. Health Check

Endpoint: GET /health_check
Description: Checks if the service is up and running. Useful for monitoring and automated service checks.

✅ Success (200 OK)

{
  "status": "ok"
}

❌ Failure (503 Service Unavailable)

{
  "status": "error",
  "message": "Service unavailable. Please try again later."
}

2. Retrieve Session Templates

Endpoint: GET /session_templates
Description: Returns all the session templates available within a specific Heat instance.

✅ Success Response

[
  {
    "id": 1,
    "name": "Default Template",
    "description": "Base template for sessions",
    "configuration": "{}",
    "nodes": []
  },
  {
    "id": 2,
    "name": "Advanced Template",
    "description": "Includes extended configurations",
    "configuration": "{}",
    "nodes": []
  }
]

3. Get Logged-in User Data

Endpoint: GET /user_data

Description: Retrieves the profile details of the currently logged-in user. This includes personal information, account status, and role information.

✅ Response Example

{
  "UserId": "f3c1e7a2-9d4b-4c0a-b5a7-6f3c73b47f29",
  "Username": "jdoe",
  "FirstName": "John",
  "LastName": "Doe",
  "Title": "Product Manager",
  "Company": "Heat Solutions",
  "Email": "jdoe@heatsolutions.com",
  "Role": "Admin",
  "CreatedAt": "2024-09-15T10:30:00Z",
  "UpdatedAt": "2025-01-10T15:45:00Z",
  "ForceChangePasswordNextSignin": false,
  "IsRegistrationComplete": true,
  "HasAcceptedDataPrivacy": true,
  "IsActive": true
}

4. Create Project

Endpoint: POST /projects
Description: Creates a new project within a Heat instance.

📨 Request Payload

{
  "Title": "Sample Project",
  "Description": "Project for testing",
  "Icon": "project_icon.png",
  "OwnerId": 123,
  "DefaultSessionTemplateId": 1
}

✅ Success (201 Created)

{
  "id": 101,
  "hexId": "a1b2c3d4",
  "title": "Simulation Project",
  "description": "A test project for distributed environments.",
  "icon": "https://example.com/icons/project.png",
  "ownerId": 501,
  "owner": {
    "id": 501,
    "email": "owner@example.com",
    "type": "Admin",
    "isActive": true,
    "createdAt": "2025-09-15T10:30:00Z",
    "externalB2CId": "ext-b2c-12345",
    "externalHEATId": "heat-98765",
    "sessionUsers": [],
    "sessionDimensions": []
  },
  "defaultSessionTemplateId": 7001,
  "defaultSessionTemplate": {},
  "createdAt": "2025-10-02T12:00:00Z"
}

❌ Failure (400 Bad Request)

{
  "status": "error",
  "message": "Invalid project data."
}

5. Update Project

Endpoint: PUT /projects/{id}
Description: Updates a specific project using the Id of the project.

📨 Request Payload

{
  "Title": "Sample Project",
  "Description": "Project for testing",
  "Icon": "project_icon.png",
  "OwnerId": 123,
  "DefaultSessionTemplateId": 1
}

✅ Success (200 OK)

(Same as Create Project Response)

❌ Failure Responses

{ "status": "error", "message": "Project not found." }
 
{ "status": "error", "message": "Invalid project data." }

6. Get Projects

Endpoint: GET /projects
Description: Retrieves all projects within a Heat instance.

✅ Response Example

[
  {
    "id": 45,
    "hexId": "a1b2c3d4",
    "title": "Sample Project",
    "description": "A test project for distributed environments.",
    "icon": "https://example.com/icons/project.png",
    "ownerId": 123,
    "owner": {
      "id": 501,
      "email": "owner@example.com",
      "type": "Admin",
      "isActive": true,
      "createdAt": "2025-09-15T10:30:00Z",
      "externalB2CId": "ext-b2c-12345",
      "externalHEATId": "heat-98765",
      "sessionUsers": [],
      "sessionDimensions": []
    },
    "defaultSessionTemplateId": 1,
    "defaultSessionTemplate": {},
    "createdAt": "2025-10-02T12:00:00Z"
  }
]

7. Get a Specific Project

Endpoint: GET /projects/{id}
Description: Retrieves a specific project using the project Id.

✅ Response Example

(Same as Get Projects Response)

❌ Failure (404 Not Found)

{
  "status": "error",
  "message": "Project not found"
}

8. Create Session

Endpoint: POST /session
Description: Creates a session associated with a given project and template.

📨 Request Payload

{
  "Name": "John Doe",
  "Email": "johndoe@example.com",
  "SimulationName": "Heat Simulation Run 1",
  "SessionTemplateId": 101,
  "ProjectId": 1,
  "Metadata": {}
}

✅ Success (201 Created)

{
  "id": "d3c5d9a2-7f29-4e7a-9f64-9b1d75c9e321",
  "name": "Example Session",
  "email": "example.user@email.com",
  "projectId": 101,
  "project": {
    "id": 101,
    "hexId": "a1b2c3d4",
    "title": "AI Research Project",
    "description": "Project focused on building simulation environments for AI models.",
    "icon": "https://example.com/icons/project-icon.png",
    "ownerId": "f42e79ab-221b-4c18-b9a3-7a53ac2a09c9",
    "owner": {
      "id": "f42e79ab-221b-4c18-b9a3-7a53ac2a09c9",
      "name": "Alice Johnson",
      "email": "alice.johnson@example.com"
    },
    "defaultSessionTemplateId": 5001,
    "defaultSessionTemplate": {
      "id": 5001,
      "name": "Default AI Simulation Template",
      "description": "Template for AI training simulations",
      "configuration": {
        "maxNodes": 10,
        "cpuLimit": "4 cores",
        "memoryLimit": "16GB"
      },
      "nodes": []
    },
    "createdAt": "2025-10-02T12:00:00Z"
  },
  "sessionTemplateId": 5001,
  "sessionTemplate": {
    "id": 5001,
    "name": "Default AI Simulation Template",
    "description": "Template for AI training simulations",
    "configuration": {
      "maxNodes": 10,
      "cpuLimit": "4 cores",
      "memoryLimit": "16GB"
    },
    "nodes": [
      {
        "id": 1,
        "type": "InputNode",
        "label": "JsonInput Node"
      },
      {
        "id": 2,
        "type": "Preprocessor",
        "label": "Preprocessing Node"
      }
    ]
  },
  "simulationName": null,
  "scenarios": [],
  "dimensions": [],
  "logoUrl": "https://example.com/logos/session-logo.png",
  "userId": "d3c5d9a2-7f29-4e7a-9f64-9b1d75c9e321",
  "metadata": null,
  "sessionUsers": [],
  "createdAt": "2025-10-02T12:30:00Z"
}

❌ Failure Response (400 Bad Request)

{
  "status": "error",
  "message": "Invalid session request. ProjectId and TemplateId are required."
}

9. Update Session

Endpoint: PATCH /sessions/{id}
Description: Update an existing session by its ID. Supports partial updates (only provided fields are changed).

Auth: Bearer token required.

Request (JSON)

Only include fields you want to change.

{
  "name": "John Doe",
  "email": "johndoe@example.com",
  "simulation_name": "Heat Simulation Run 1",
  "session_template_id": 101,
  "project_id": 1,
  "metadata": {}
}
  • email validated if provided.
  • metadata must be valid JSON (sent upstream as a JSON string).

Responses

200 OK

Returns the full updated session, including node instances and default ingestion node id.

{
  "id": "6d551cfb-6f3f-41cc-a48a-b6eb1f7f3abb",
  "name": "Training Session",
  "email": "trainer@example.com",
  "simulation_name": "Network Optimization",
  "project_id": 101,
  "project": {
    "hex_id": "a1b2c3d4",
    "title": "AI Research Project",
    "description": "Project for testing and simulating AI workflows.",
    "icon": "https://example.com/icons/project.png",
    "owner_id": 501,
    "default_session_template_id": 7001,
    "created_at": "2025-10-02T12:00:00Z"
  },
  "session_template_id": 7001,
  "session_template": {
    "name": "Default Template",
    "description": "Template used by default",
    "configuration": "{}"
  },
  "metadata": {},
  "logo_url": "https://example.com/logos/session.png",
  "node_instances": [],
  "default_ingestion_node_id": null,
  "session_users": [],
  "dimensions": [],
  "scenarios": []
}

400 Bad Request

{ "status": "error", "message": "Invalid session data" }

401 Unauthorized / 403 Forbidden

{ "status": "error", "message": "Unauthorized" }
{ "status": "error", "message": "Forbidden" }

404 Not Found

{ "status": "error", "message": "Session not found" }

Notes

  • Partial updates: omit fields you don’t want to change.
  • Snake case: paths and fields use snake_case (/sessions, session_template_id, etc.).
  • Project & Template IDs: must reference valid records.
  • Controller enriches the response with node_instances (same as creation flow).

Example

curl -X PATCH "https://your-host/api/v2/sessions/6d551cfb-6f3f-41cc-a48a-b6eb1f7f3abb"   -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json"   -d '{"name":"John Doe","project_id":1,"metadata":{"a":1}}'

10. Add Scenario Instance to a Session

Endpoint: POST /{sessionId}/scenario_instances
Description: Creates a scenario using a session and returns the corresponding scenarioId.

📨 Request Payload

{
  "simulationId": "string",
  "scenarioName": "string",
  "scenarioInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "from": "2025-10-02T10:39:24.760Z",
  "to": "2025-10-02T10:39:24.760Z"
}

✅ Success (200 OK)

{
  "status": true,
  "message": "Scenario instance retrieved successfully",
  "template": {
    "simulationId": 67890,
    "sessionId": 54321,
    "scenarioName": "Test Scenario A",
    "scenarioInstanceId": "scn-001",
    "from": "2025-10-01T08:00:00Z",
    "to": "2025-10-01T10:00:00Z",
    "dimensions": [],
    "createdAt": "2025-10-02T12:00:00Z"
  }
}

❌ Failure

{ "status": "error", "message": "SessionId not found." }
 
{ "status": "error", "message": "Invalid request. Scenarion name is required." }

11. Get Configurations

Endpoint: GET /config/all
Description: Retrieves all platform configurations.

✅ Success (200 OK)

{
  "public_api_v1": {
    "AzureAdB2CSettings": {},
    "BlobStorageSettings": {},
    "SendGridSettings": {},
    "ContactSupportSettings": {},
    "ConnectionStrings": {}
  }
}

12. Create Configuration

Endpoint: POST /config
Description: Creates a new platform configuration.

📨 Request Payload Example

{
  "name": "string",
  "valueType": 0,
  "value": "string",
  "description": "string"
}

✅ Success (201 Created)

{
  "id": 1001,
  "name": "MaxTrainingEpochs",
  "valueType": 2,
  "value": "50",
  "description": "Maximum number of epochs allowed for training models in this project.",
  "createdAt": "2025-10-01T10:00:00Z",
  "updatedAt": "2025-10-02T12:30:00Z"
}

❌ Failure (400 Bad Request)

{
  "status": "error",
  "message": "Invalid configuration name"
}

❌ Failure (409 Conflict)

{
  "status": "error",
  "message": "Configuration with the same name already exists."
}

13. Update Configuration

Endpoint: PUT /config/{name}
Description: Updates an existing platform configuration by name.

📨 Request Payload Example

{
  "name": "string",
  "valueType": 0,
  "value": "string",
  "description": "string"
}

✅ Success (200 OK)

{
  "id": 1001,
  "name": "MaxTrainingEpochs",
  "valueType": 2,
  "value": "50",
  "description": "Maximum number of epochs allowed for training models in this project.",
  "createdAt": "2025-10-01T10:00:00Z",
  "updatedAt": "2025-10-02T12:30:00Z"
}

❌ Failure

{
  "status": "error",
  "message": "Invalid configuration name."
}
 
{
  "status": "error",
  "message": "Configuration not found"
}
External API V2Overview