REST API Reference

This document summarizes the main REST endpoints used when working with HiStruct components, templates, PVC state, and evaluated outputs.

Authentication

HiStruct uses authenticated browser-style sessions rather than simple bearer-token API calls.

Login flow

• Sign in through the idd.histruct.com OIDC flow
• The login process establishes session cookies
• Subsequent API calls must include the authenticated session

PowerShell usage

When testing from PowerShell, use a persistent WebSession so cookies are preserved across requests.

Example:

$session = New-Object Microsoft.PowerShell.Commands.WebRequestSession
Invoke-WebRequest -Uri "https://idd.histruct.com" -WebSession $session

privateKey

Some component-specific endpoints require a privateKey query parameter.

This key is usually returned when a component is created and acts as a component access token for later operations.

Component Lifecycle Endpoints

Create component

POST /{space}/{lang}/inquiry/new-configuration

Request body:

{
  "FccRef": "MyComponent.fcc",
  "PvcJsonString": "{}"
}

Response:

{
  "editComponentUrl": "...",
  "privateKey": "...",
  "componentId": 479408,
  "projectId": 473840
}

Use this endpoint to create a new component instance from a palette template.

Read palette

GET /api/static/{space}/raw-palette-items

Permissions:

• SpaceDeveloper

Use this endpoint to inspect the palette items registered for a space.

Update palette

POST /api/static/{space}/raw-palette-items

Permissions:

• SpaceDeveloper

Use this endpoint to publish or update palette configuration.

Check session and roles

GET /{space}/{lang}/Model/UserSession

This is the main diagnostic endpoint for:

• authentication status
• active roles
• space-specific access issues

If an API call fails due to permissions, check this endpoint first.

Get component metadata

GET /api/spaces/{space}/components/{id}/details

Returns component-level metadata such as identifiers, links, and template/prototype-related information.

Get current PVC

GET /api/spaces/{space}/components/{id}/pvc-json

Returns the current PVC state for a component instance.

This is useful for:

• debugging form state
• comparing current values to template defaults
• generating test payloads for updates

Expression Evaluation

Evaluate expression

POST /api/spaces/{space}/components/{id}/expression?privateKey={key}

Request body:

{
  "Expression": "outSummary"
}

Example response:

{
  "Result": "Roof: 10.0 x 4.5 m | Slope: 26.6° | Area: 89.4 m²"
}

This endpoint evaluates an FCS expression in the context of the component's current FCS + PVC state.

Special expression: ?pvcJson

You can also request the current PVC state via a special expression.

Example concept:

{
  "Expression": "?pvcJson"
}

Use this for lightweight state inspection when you are already working with the expression API surface.

Example PowerShell call

$body = @{ Expression = "outSummary" } | ConvertTo-Json
Invoke-RestMethod `
  -Method Post `
  -Uri "https://example.com/api/spaces/sky/components/479408/expression?privateKey=abc123" `
  -WebSession $session `
  -ContentType "application/json" `
  -Body $body

Scene Generation (3D)

Update scene

POST /api/spaces/{space}/components/{id}/hi-scene-update?privateKey={key}

Request body:

{
  "viewName": "viewDefault",
  "viewPvcUpdater": "{}",
  "ownedSceneHashes": ""
}

Example response:

{
  "scene3Djson": {
    "nodes": []
  },
  "ProjectionSettings": {
    "cameraTarget": [0, 0, 0]
  }
}

This endpoint evaluates the component and returns the data needed to render the 3D scene.

Request fields

• viewName - the named view to render, such as viewDefault
• viewPvcUpdater - PVC overrides applied for the scene request
• ownedSceneHashes - client-owned scene hashes for incremental updates or reuse

Response fields

• scene3Djson - scene payload for the viewer
• ProjectionSettings - camera/projection configuration used by the view

Parameter Updates

Two related endpoints are commonly used for updating component properties.

Modern endpoint

POST /api/spaces/{space}/components/{id}/update-properties

Legacy endpoint

POST /{space}/{lang}/Properties/ComponentEditTransaction

These requests commit or stage PVC changes through the parameter editing system.

Request body type

The request body is a ContextEditContextRequestDto.

Important fields include:

• vm (ContextParamValueViewModel)
• validationTrigger
• observedContexts
• navigationContexts

Conceptual shape

{
  "vm": {
    "OriginalPvcB64": "...",
    "StagingEditedPvcB64": "..."
  },
  "validationTrigger": "UserEdit",
  "observedContexts": [],
  "navigationContexts": []
}

Notes

• OriginalPvcB64 is the previous PVC snapshot
• StagingEditedPvcB64 is the edited PVC snapshot
• the server validates and commits the new PVC state

Prototype Management

Try refresh prototype

POST /api/spaces/{space}/components/{id}/template-prototype-try-refresh

Purpose:

• triggers the Shift+R style prototype refresh flow
• re-resolves the component against the updated template/prototype source

Permissions:

• Admin only

This is especially useful when template code changed and you need the component instance to refresh against the newer FCS definition.

Typical Workflow Example

A normal integration flow often looks like this:

1. Authenticate and establish a cookie session
2. Create a component with new-configuration
3. Save componentId and privateKey
4. Read current PVC with /pvc-json
5. Update parameters with update-properties or ComponentEditTransaction
6. Evaluate summary outputs with /expression
7. Render the 3D scene with /hi-scene-update
8. If needed, refresh the prototype with template-prototype-try-refresh

Endpoint Summary Table

Practical Notes

• Always verify auth with UserSession before debugging deeper issues.
• Keep the privateKey returned from component creation if later component-scoped endpoints need it.
• Treat PVC as the live instance state and FCS as the template definition.
• Use expression evaluation for quick diagnostics and scene update for full 3D output.