openapi: 3.0.3
info:
  title: SimScale REST API
  description: The SimScale REST API provides programmatic access to the SimScale cloud simulation platform. Manage projects, upload CAD geometry, configure meshing, run CFD/FEA/thermal simulations, and retrieve results. Requires an Enterprise plan and an API key.
  version: '0.0.0'
  contact:
    name: SimScale Support
    url: https://www.simscale.com/support/
  termsOfService: https://www.simscale.com/terms-of-service/
externalDocs:
  description: SimScale API and SDK Documentation
  url: https://www.simscale.com/docs/platform/api-and-sdk-documentation/
servers:
- url: https://api.simscale.com
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: Projects
  description: Simulation project management
- name: Geometry
  description: CAD geometry upload and import
- name: Simulations
  description: Simulation setup and configuration
- name: Mesh Operations
  description: Mesh generation and configuration
- name: Simulation Runs
  description: Simulation execution and status
- name: Reports
  description: Post-processing and results reporting
- name: Storage
  description: File storage management
paths:
  /v0/projects:
    get:
      operationId: listProjects
      summary: List Projects
      description: Retrieve a list of all simulation projects for the authenticated user.
      tags:
      - Projects
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          default: 25
          maximum: 100
        description: Number of projects to return
      - name: page
        in: query
        schema:
          type: integer
          default: 0
        description: Page number (zero-indexed)
      responses:
        '200':
          description: List of projects
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectList'
        '401':
          description: Unauthorized - invalid API key
    post:
      operationId: createProject
      summary: Create Project
      description: Create a new simulation project.
      tags:
      - Projects
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectInput'
      responses:
        '201':
          description: Project created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          description: Invalid project data
  /v0/projects/{project_id}:
    get:
      operationId: getProject
      summary: Get Project
      description: Retrieve details of a specific simulation project.
      tags:
      - Projects
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
        description: Unique project identifier
      responses:
        '200':
          description: Project details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '404':
          description: Project not found
    put:
      operationId: updateProject
      summary: Update Project
      description: Update the name or description of an existing project.
      tags:
      - Projects
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
        description: Unique project identifier
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectInput'
      responses:
        '200':
          description: Project updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
    delete:
      operationId: deleteProject
      summary: Delete Project
      description: Delete a simulation project and all its associated data.
      tags:
      - Projects
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
        description: Unique project identifier
      responses:
        '200':
          description: Project deleted
  /v0/storage:
    post:
      operationId: createStorage
      summary: Create Storage
      description: Create a storage location for uploading a CAD file. Returns a presigned upload URL.
      tags:
      - Storage
      responses:
        '200':
          description: Storage location created with upload URL
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorageLocation'
  /v0/projects/{project_id}/geometries:
    get:
      operationId: listGeometries
      summary: List Geometries
      description: Retrieve all CAD geometries imported into a project.
      tags:
      - Geometry
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
        description: Unique project identifier
      responses:
        '200':
          description: List of geometries
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeometryList'
    post:
      operationId: importGeometry
      summary: Import Geometry
      description: Import a CAD geometry file (previously uploaded to storage) into a project.
      tags:
      - Geometry
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
        description: Unique project identifier
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GeometryImportRequest'
      responses:
        '201':
          description: Geometry import initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Geometry'
  /v0/projects/{project_id}/geometries/{geometry_id}:
    get:
      operationId: getGeometry
      summary: Get Geometry
      description: Retrieve details and status of a specific geometry import.
      tags:
      - Geometry
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      - name: geometry_id
        in: path
        required: true
        schema:
          type: string
        description: Unique geometry identifier
      responses:
        '200':
          description: Geometry details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Geometry'
        '404':
          description: Geometry not found
  /v0/projects/{project_id}/simulations:
    get:
      operationId: listSimulations
      summary: List Simulations
      description: Retrieve all simulations defined within a project.
      tags:
      - Simulations
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: List of simulations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulationList'
    post:
      operationId: createSimulation
      summary: Create Simulation
      description: Create a new simulation specification within a project, specifying the physics model and geometry.
      tags:
      - Simulations
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimulationInput'
      responses:
        '201':
          description: Simulation created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Simulation'
  /v0/projects/{project_id}/simulations/{simulation_id}:
    get:
      operationId: getSimulation
      summary: Get Simulation
      description: Retrieve the full specification and status of a specific simulation.
      tags:
      - Simulations
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      - name: simulation_id
        in: path
        required: true
        schema:
          type: string
        description: Unique simulation identifier
      responses:
        '200':
          description: Simulation details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Simulation'
        '404':
          description: Simulation not found
    put:
      operationId: updateSimulation
      summary: Update Simulation
      description: Update the specification of an existing simulation.
      tags:
      - Simulations
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      - name: simulation_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimulationInput'
      responses:
        '200':
          description: Simulation updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Simulation'
  /v0/projects/{project_id}/mesh-operations:
    get:
      operationId: listMeshOperations
      summary: List Mesh Operations
      description: Retrieve all mesh generation operations within a project.
      tags:
      - Mesh Operations
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: List of mesh operations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeshOperationList'
    post:
      operationId: createMeshOperation
      summary: Create Mesh Operation
      description: Create a new mesh generation operation for a geometry.
      tags:
      - Mesh Operations
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MeshOperationInput'
      responses:
        '201':
          description: Mesh operation created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeshOperation'
  /v0/projects/{project_id}/mesh-operations/{mesh_operation_id}:
    get:
      operationId: getMeshOperation
      summary: Get Mesh Operation
      description: Retrieve the status and details of a specific mesh operation.
      tags:
      - Mesh Operations
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      - name: mesh_operation_id
        in: path
        required: true
        schema:
          type: string
        description: Unique mesh operation identifier
      responses:
        '200':
          description: Mesh operation details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeshOperation'
        '404':
          description: Mesh operation not found
  /v0/projects/{project_id}/mesh-operations/{mesh_operation_id}/start:
    post:
      operationId: startMeshOperation
      summary: Start Mesh Operation
      description: Trigger execution of a mesh generation operation.
      tags:
      - Mesh Operations
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      - name: mesh_operation_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Mesh operation started
  /v0/projects/{project_id}/simulations/{simulation_id}/runs:
    get:
      operationId: listSimulationRuns
      summary: List Simulation Runs
      description: Retrieve all execution runs for a specific simulation.
      tags:
      - Simulation Runs
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      - name: simulation_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: List of simulation runs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulationRunList'
    post:
      operationId: createSimulationRun
      summary: Create Simulation Run
      description: Create and start a new execution run for a simulation.
      tags:
      - Simulation Runs
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      - name: simulation_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Name for this run
      responses:
        '201':
          description: Simulation run created and started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulationRun'
  /v0/projects/{project_id}/simulations/{simulation_id}/runs/{run_id}:
    get:
      operationId: getSimulationRun
      summary: Get Simulation Run
      description: Retrieve the status and progress of a specific simulation run.
      tags:
      - Simulation Runs
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      - name: simulation_id
        in: path
        required: true
        schema:
          type: string
      - name: run_id
        in: path
        required: true
        schema:
          type: string
        description: Unique run identifier
      responses:
        '200':
          description: Simulation run details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulationRun'
        '404':
          description: Run not found
  /v0/projects/{project_id}/simulations/{simulation_id}/runs/{run_id}/results:
    get:
      operationId: getSimulationResults
      summary: Get Simulation Results
      description: Retrieve result data and download links for a completed simulation run.
      tags:
      - Reports
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
      - name: simulation_id
        in: path
        required: true
        schema:
          type: string
      - name: run_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Simulation results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulationResults'
        '404':
          description: Results not found
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: SimScale API key. Generate in your SimScale account settings.
  schemas:
    Project:
      type: object
      properties:
        projectId:
          type: string
          description: Unique project identifier
        name:
          type: string
          description: Project name
        description:
          type: string
          description: Project description
        measurementSystem:
          type: string
          enum:
          - SI
          - US
          description: Unit system used in the project
        created:
          type: string
          format: date-time
        modified:
          type: string
          format: date-time
        geometryCount:
          type: integer
          description: Number of geometries in the project
        simulationCount:
          type: integer
          description: Number of simulations in the project
    ProjectList:
      type: object
      properties:
        projects:
          type: array
          items:
            $ref: '#/components/schemas/Project'
        totalCount:
          type: integer
    ProjectInput:
      type: object
      required:
      - name
      properties:
        name:
          type: string
        description:
          type: string
        measurementSystem:
          type: string
          enum:
          - SI
          - US
          default: SI
    StorageLocation:
      type: object
      properties:
        storageId:
          type: string
          description: Storage location identifier
        url:
          type: string
          description: Pre-signed URL for uploading the file via HTTP PUT
    Geometry:
      type: object
      properties:
        geometryId:
          type: string
          description: Unique geometry identifier
        name:
          type: string
        status:
          type: string
          enum:
          - UPLOADING
          - PROCESSING
          - FINISHED
          - FAILED
        format:
          type: string
          enum:
          - PARASOLID
          - STEP
          - IGES
          - STL
          description: CAD file format
        numberOfSolids:
          type: integer
        numberOfSurfaces:
          type: integer
        created:
          type: string
          format: date-time
    GeometryList:
      type: object
      properties:
        geometries:
          type: array
          items:
            $ref: '#/components/schemas/Geometry'
        totalCount:
          type: integer
    GeometryImportRequest:
      type: object
      required:
      - name
      - storageId
      - format
      properties:
        name:
          type: string
        storageId:
          type: string
          description: Storage ID from createStorage response
        format:
          type: string
          enum:
          - PARASOLID
          - STEP
          - IGES
          - STL
    Simulation:
      type: object
      properties:
        simulationId:
          type: string
        name:
          type: string
        type:
          type: string
          enum:
          - INCOMPRESSIBLE
          - COMPRESSIBLE
          - CONJUGATE_HEAT_TRANSFER
          - CONVECTIVE_HEAT_TRANSFER
          - STRUCTURAL
          - DYNAMIC
          - PEDESTRIAN_WIND_COMFORT
          description: Physics model type
        geometryId:
          type: string
          description: Associated geometry identifier
        status:
          type: string
          enum:
          - DRAFT
          - COMPUTED
          - INVALID
        created:
          type: string
          format: date-time
        modified:
          type: string
          format: date-time
    SimulationList:
      type: object
      properties:
        simulations:
          type: array
          items:
            $ref: '#/components/schemas/Simulation'
        totalCount:
          type: integer
    SimulationInput:
      type: object
      required:
      - name
      - type
      - geometryId
      properties:
        name:
          type: string
        type:
          type: string
          enum:
          - INCOMPRESSIBLE
          - COMPRESSIBLE
          - CONJUGATE_HEAT_TRANSFER
          - CONVECTIVE_HEAT_TRANSFER
          - STRUCTURAL
          - DYNAMIC
          - PEDESTRIAN_WIND_COMFORT
        geometryId:
          type: string
        model:
          type: object
          description: Physics model configuration (simulation-type specific)
          additionalProperties: true
    MeshOperation:
      type: object
      properties:
        meshOperationId:
          type: string
        name:
          type: string
        geometryId:
          type: string
        status:
          type: string
          enum:
          - PENDING
          - RUNNING
          - FINISHED
          - FAILED
          - CANCELED
        meshId:
          type: string
          description: Generated mesh identifier (after completion)
        created:
          type: string
          format: date-time
        finishedAt:
          type: string
          format: date-time
    MeshOperationList:
      type: object
      properties:
        meshOperations:
          type: array
          items:
            $ref: '#/components/schemas/MeshOperation'
    MeshOperationInput:
      type: object
      required:
      - name
      - geometryId
      properties:
        name:
          type: string
        geometryId:
          type: string
        meshingType:
          type: string
          enum:
          - STITCHED_SURFACE
          - SWEPT
          - PARAMETRIC_HEX_CORE
          - AUTOMATIC
          default: AUTOMATIC
        refinements:
          type: array
          items:
            type: object
          description: Region-specific mesh refinements
    SimulationRun:
      type: object
      properties:
        runId:
          type: string
        name:
          type: string
        simulationId:
          type: string
        status:
          type: string
          enum:
          - PENDING
          - RUNNING
          - FINISHED
          - FAILED
          - CANCELED
        progress:
          type: number
          format: float
          minimum: 0
          maximum: 100
          description: Completion percentage
        startTime:
          type: string
          format: date-time
        finishedTime:
          type: string
          format: date-time
    SimulationRunList:
      type: object
      properties:
        runs:
          type: array
          items:
            $ref: '#/components/schemas/SimulationRun'
    SimulationResults:
      type: object
      properties:
        runId:
          type: string
        status:
          type: string
          enum:
          - PENDING
          - AVAILABLE
        outputs:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              type:
                type: string
                enum:
                - SCALAR_FIELD
                - VECTOR_FIELD
                - SURFACE_DATA
                - POINT_DATA
              downloadUrl:
                type: string
                description: Presigned download URL
              format:
                type: string
                enum:
                - VTK
                - CSV
                - JSON