HSMs

List HSMs

get

https://internal-api.platform.amigo.aihttps://api.platform.amigo.ai

/v1/{workspace_id}/hsms/

List HSMs in a workspace with pagination. Requires Hsm.view permission.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Query parameters

sort_byany ofOptional

stringOptional

or

nullOptional

limitinteger · max: 20OptionalDefault: 10

continuation_tokenintegerOptionalDefault: 0

Responses

200

Successful Response

application/json

has_morebooleanRequired

continuation_tokenany ofOptional

integerOptional

or

nullOptional

401

Missing or invalid API key.

403

Insufficient permissions.

404

Not found.

422

Validation Error

application/json

get

/v1/{workspace_id}/hsms/

HTTPcURLJavaScriptPython

GET /v1/{workspace_id}/hsms/ HTTP/1.1
Host: internal-api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "id": "text",
      "workspace_id": "text",
      "name": "text",
      "description": "text",
      "latest_version": 1,
      "state_count": 1,
      "created_at": "2026-03-22T05:27:56.948Z",
      "updated_at": "2026-03-22T05:27:56.948Z"
    }
  ],
  "has_more": true,
  "continuation_token": 1
}

Create an HSM

post

https://internal-api.platform.amigo.aihttps://api.platform.amigo.ai

/v1/{workspace_id}/hsms/

Create a new HSM in a workspace. Requires Hsm.create permission.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Body

application/json

namestring · min: 1Required

descriptionstringOptionalDefault: ""

Responses

201

Successful Response

application/json

401

Missing or invalid API key.

403

Insufficient permissions.

404

Not found.

409

Name already taken.

422

Invalid request body.

post

/v1/{workspace_id}/hsms/

HTTPcURLJavaScriptPython

POST /v1/{workspace_id}/hsms/ HTTP/1.1
Host: internal-api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 32

{
  "name": "text",
  "description": ""
}

{
  "id": "text",
  "workspace_id": "text",
  "name": "text",
  "description": "text",
  "latest_version": 1,
  "state_count": 1,
  "created_at": "2026-03-22T05:27:56.948Z",
  "updated_at": "2026-03-22T05:27:56.948Z"
}

Get an HSM

get

https://internal-api.platform.amigo.aihttps://api.platform.amigo.ai

/v1/{workspace_id}/hsms/{hsm_id}

Retrieve an HSM by ID. Requires Hsm.view permission.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

hsm_idstring · uuidRequired

Responses

200

Successful Response

application/json

idstringRequired

workspace_idstringRequired

namestringRequired

descriptionstringRequired

latest_versionany ofOptional

integerOptional

or

nullOptional

state_countany ofOptional

integerOptional

or

nullOptional

created_atstring · date-timeRequired

updated_atstring · date-timeRequired

401

Missing or invalid API key.

403

Insufficient permissions.

404

Not found.

422

Validation Error

application/json

get

/v1/{workspace_id}/hsms/{hsm_id}

HTTPcURLJavaScriptPython

GET /v1/{workspace_id}/hsms/{hsm_id} HTTP/1.1
Host: internal-api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "text",
  "workspace_id": "text",
  "name": "text",
  "description": "text",
  "latest_version": 1,
  "state_count": 1,
  "created_at": "2026-03-22T05:27:56.948Z",
  "updated_at": "2026-03-22T05:27:56.948Z"
}

Update an HSM

put

https://internal-api.platform.amigo.aihttps://api.platform.amigo.ai

/v1/{workspace_id}/hsms/{hsm_id}

Update an HSM's name or description. Requires Hsm.update permission.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

hsm_idstring · uuidRequired

Body

application/json

nameany ofOptional

string · min: 1Optional

or

nullOptional

descriptionany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

idstringRequired

workspace_idstringRequired

namestringRequired

descriptionstringRequired

latest_versionany ofOptional

integerOptional

or

nullOptional

state_countany ofOptional

integerOptional

or

nullOptional

created_atstring · date-timeRequired

updated_atstring · date-timeRequired

401

Missing or invalid API key.

403

Insufficient permissions.

404

Not found.

409

Name already taken.

422

Invalid request body.

put

/v1/{workspace_id}/hsms/{hsm_id}

HTTPcURLJavaScriptPython

PUT /v1/{workspace_id}/hsms/{hsm_id} HTTP/1.1
Host: internal-api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 36

{
  "name": "text",
  "description": "text"
}

{
  "id": "text",
  "workspace_id": "text",
  "name": "text",
  "description": "text",
  "latest_version": 1,
  "state_count": 1,
  "created_at": "2026-03-22T05:27:56.948Z",
  "updated_at": "2026-03-22T05:27:56.948Z"
}

Delete an HSM

delete

https://internal-api.platform.amigo.aihttps://api.platform.amigo.ai

/v1/{workspace_id}/hsms/{hsm_id}

Delete an HSM. HSM versions are retained. Requires Hsm.delete permission.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

hsm_idstring · uuidRequired

Responses

204

Successful Response

401

Missing or invalid API key.

403

Insufficient permissions.

404

Not found.

422

Validation Error

application/json

delete

/v1/{workspace_id}/hsms/{hsm_id}

HTTPcURLJavaScriptPython

DELETE /v1/{workspace_id}/hsms/{hsm_id} HTTP/1.1
Host: internal-api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

List HSM versions

get

https://internal-api.platform.amigo.aihttps://api.platform.amigo.ai

/v1/{workspace_id}/hsms/{hsm_id}/versions

List versions of an HSM with pagination. Requires Hsm.view permission.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

hsm_idstring · uuidRequired

Query parameters

sort_byany ofOptional

stringOptional

or

nullOptional

limitinteger · max: 20OptionalDefault: 10

continuation_tokenintegerOptionalDefault: 0

Responses

200

Successful Response

application/json

has_morebooleanRequired

continuation_tokenany ofOptional

integerOptional

or

nullOptional

401

Missing or invalid API key.

403

Insufficient permissions.

404

Not found.

422

Validation Error

application/json

get

/v1/{workspace_id}/hsms/{hsm_id}/versions

HTTPcURLJavaScriptPython

GET /v1/{workspace_id}/hsms/{hsm_id}/versions HTTP/1.1
Host: internal-api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "id": "text",
      "workspace_id": "text",
      "hsm_id": "text",
      "version": 1,
      "name": "text",
      "description": "text",
      "states": [
        {
          "type": "text",
          "name": "text",
          "objective": "text",
          "actions": [
            {
              "description": "text",
              "filler_hint": "text"
            }
          ],
          "intra_state_navigation_guidelines": [
            "text"
          ],
          "action_guidelines": [
            "text"
          ],
          "boundary_constraints": [
            "text"
          ],
          "exit_conditions": [
            {
              "description": "text",
              "next_state": "text",
              "filler_hint": "text"
            }
          ],
          "action_tool_call_specs": [
            {
              "tool_id": "text",
              "version_constraint": "text",
              "additional_instruction": "text",
              "audio_fillers": [
                "text"
              ],
              "audio_filler_triggered_after": 0,
              "result_persistence": "ephemeral"
            }
          ],
          "exit_condition_tool_call_specs": [
            {
              "tool_id": "text",
              "version_constraint": "text",
              "additional_instruction": "text",
              "audio_fillers": [
                "text"
              ],
              "audio_filler_triggered_after": 0,
              "result_persistence": "ephemeral"
            }
          ],
          "skip_active_memory_retrieval": true,
          "escalation_config": {
            "topic_risk_score": 0,
            "auto_escalate_threshold": 1,
            "max_loop_count": 3,
            "operator_skill": "text"
          }
        }
      ],
      "new_user_initial_state": "text",
      "returning_user_initial_state": "text",
      "terminal_state": "text",
      "references": {
        "ANY_ADDITIONAL_PROPERTY": []
      },
      "global_intra_state_navigation_guidelines": [
        "text"
      ],
      "global_action_guidelines": [
        "text"
      ],
      "global_boundary_constraints": [
        "text"
      ],
      "topology_description": "text",
      "created_at": "2026-03-22T05:27:56.948Z",
      "updated_at": "2026-03-22T05:27:56.948Z"
    }
  ],
  "has_more": true,
  "continuation_token": 1
}

Create an HSM version

post

https://internal-api.platform.amigo.aihttps://api.platform.amigo.ai

/v1/{workspace_id}/hsms/{hsm_id}/versions

Create a new version of an HSM. Version number is auto-incremented. Requires Hsm.create permission.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

hsm_idstring · uuidRequired

Body

application/json

namestringOptionalDefault: ""

descriptionstringOptionalDefault: ""

new_user_initial_statestringRequired

returning_user_initial_statestringRequired

terminal_statestringRequired

global_intra_state_navigation_guidelinesstring[]OptionalDefault: []

global_action_guidelinesstring[]OptionalDefault: []

global_boundary_constraintsstring[]OptionalDefault: []

topology_descriptionany ofOptional

stringOptional

or

nullOptional

Responses

201

Successful Response

application/json

401

Missing or invalid API key.

403

Insufficient permissions.

404

Not found.

409

Name already taken.

422

Invalid request body.

post

/v1/{workspace_id}/hsms/{hsm_id}/versions

HTTPcURLJavaScriptPython

POST /v1/{workspace_id}/hsms/{hsm_id}/versions HTTP/1.1
Host: internal-api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1181

{
  "name": "",
  "description": "",
  "states": [
    {
      "type": "text",
      "name": "text",
      "objective": "text",
      "actions": [
        {
          "description": "text",
          "filler_hint": "text"
        }
      ],
      "intra_state_navigation_guidelines": [
        "text"
      ],
      "action_guidelines": [
        "text"
      ],
      "boundary_constraints": [
        "text"
      ],
      "exit_conditions": [
        {
          "description": "text",
          "next_state": "text",
          "filler_hint": "text"
        }
      ],
      "action_tool_call_specs": [
        {
          "tool_id": "text",
          "version_constraint": "text",
          "additional_instruction": "text",
          "audio_fillers": [
            "text"
          ],
          "audio_filler_triggered_after": 0,
          "result_persistence": "ephemeral"
        }
      ],
      "exit_condition_tool_call_specs": [
        {
          "tool_id": "text",
          "version_constraint": "text",
          "additional_instruction": "text",
          "audio_fillers": [
            "text"
          ],
          "audio_filler_triggered_after": 0,
          "result_persistence": "ephemeral"
        }
      ],
      "skip_active_memory_retrieval": true,
      "escalation_config": {
        "topic_risk_score": 0,
        "auto_escalate_threshold": 1,
        "max_loop_count": 3,
        "operator_skill": "text"
      }
    }
  ],
  "new_user_initial_state": "text",
  "returning_user_initial_state": "text",
  "terminal_state": "text",
  "references": {
    "ANY_ADDITIONAL_PROPERTY": []
  },
  "global_intra_state_navigation_guidelines": [
    "text"
  ],
  "global_action_guidelines": [
    "text"
  ],
  "global_boundary_constraints": [
    "text"
  ],
  "topology_description": "text"
}

{
  "id": "text",
  "workspace_id": "text",
  "hsm_id": "text",
  "version": 1,
  "name": "text",
  "description": "text",
  "states": [
    {
      "type": "text",
      "name": "text",
      "objective": "text",
      "actions": [
        {
          "description": "text",
          "filler_hint": "text"
        }
      ],
      "intra_state_navigation_guidelines": [
        "text"
      ],
      "action_guidelines": [
        "text"
      ],
      "boundary_constraints": [
        "text"
      ],
      "exit_conditions": [
        {
          "description": "text",
          "next_state": "text",
          "filler_hint": "text"
        }
      ],
      "action_tool_call_specs": [
        {
          "tool_id": "text",
          "version_constraint": "text",
          "additional_instruction": "text",
          "audio_fillers": [
            "text"
          ],
          "audio_filler_triggered_after": 0,
          "result_persistence": "ephemeral"
        }
      ],
      "exit_condition_tool_call_specs": [
        {
          "tool_id": "text",
          "version_constraint": "text",
          "additional_instruction": "text",
          "audio_fillers": [
            "text"
          ],
          "audio_filler_triggered_after": 0,
          "result_persistence": "ephemeral"
        }
      ],
      "skip_active_memory_retrieval": true,
      "escalation_config": {
        "topic_risk_score": 0,
        "auto_escalate_threshold": 1,
        "max_loop_count": 3,
        "operator_skill": "text"
      }
    }
  ],
  "new_user_initial_state": "text",
  "returning_user_initial_state": "text",
  "terminal_state": "text",
  "references": {
    "ANY_ADDITIONAL_PROPERTY": []
  },
  "global_intra_state_navigation_guidelines": [
    "text"
  ],
  "global_action_guidelines": [
    "text"
  ],
  "global_boundary_constraints": [
    "text"
  ],
  "topology_description": "text",
  "created_at": "2026-03-22T05:27:56.948Z",
  "updated_at": "2026-03-22T05:27:56.948Z"
}

Get an HSM version

get

https://internal-api.platform.amigo.aihttps://api.platform.amigo.ai

/v1/{workspace_id}/hsms/{hsm_id}/versions/{version}

Retrieve a specific HSM version by number, or 'latest'. Requires Hsm.view permission.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

hsm_idstring · uuidRequired

versionany ofRequired

integerOptional

or

stringOptional

Responses

200

Successful Response

application/json

idstringRequired

workspace_idstringRequired

hsm_idstringRequired

versionintegerRequired

namestringRequired

descriptionstringRequired

new_user_initial_statestringRequired

returning_user_initial_statestringRequired

terminal_statestringRequired

global_intra_state_navigation_guidelinesstring[]Required

global_action_guidelinesstring[]Required

global_boundary_constraintsstring[]Required

topology_descriptionany ofRequired

stringOptional

or

nullOptional

created_atstring · date-timeRequired

updated_atstring · date-timeRequired

401

Missing or invalid API key.

403

Insufficient permissions.

404

Not found.

422

Validation Error

application/json

get

/v1/{workspace_id}/hsms/{hsm_id}/versions/{version}

HTTPcURLJavaScriptPython

GET /v1/{workspace_id}/hsms/{hsm_id}/versions/{version} HTTP/1.1
Host: internal-api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "text",
  "workspace_id": "text",
  "hsm_id": "text",
  "version": 1,
  "name": "text",
  "description": "text",
  "states": [
    {
      "type": "text",
      "name": "text",
      "objective": "text",
      "actions": [
        {
          "description": "text",
          "filler_hint": "text"
        }
      ],
      "intra_state_navigation_guidelines": [
        "text"
      ],
      "action_guidelines": [
        "text"
      ],
      "boundary_constraints": [
        "text"
      ],
      "exit_conditions": [
        {
          "description": "text",
          "next_state": "text",
          "filler_hint": "text"
        }
      ],
      "action_tool_call_specs": [
        {
          "tool_id": "text",
          "version_constraint": "text",
          "additional_instruction": "text",
          "audio_fillers": [
            "text"
          ],
          "audio_filler_triggered_after": 0,
          "result_persistence": "ephemeral"
        }
      ],
      "exit_condition_tool_call_specs": [
        {
          "tool_id": "text",
          "version_constraint": "text",
          "additional_instruction": "text",
          "audio_fillers": [
            "text"
          ],
          "audio_filler_triggered_after": 0,
          "result_persistence": "ephemeral"
        }
      ],
      "skip_active_memory_retrieval": true,
      "escalation_config": {
        "topic_risk_score": 0,
        "auto_escalate_threshold": 1,
        "max_loop_count": 3,
        "operator_skill": "text"
      }
    }
  ],
  "new_user_initial_state": "text",
  "returning_user_initial_state": "text",
  "terminal_state": "text",
  "references": {
    "ANY_ADDITIONAL_PROPERTY": []
  },
  "global_intra_state_navigation_guidelines": [
    "text"
  ],
  "global_action_guidelines": [
    "text"
  ],
  "global_boundary_constraints": [
    "text"
  ],
  "topology_description": "text",
  "created_at": "2026-03-22T05:27:56.948Z",
  "updated_at": "2026-03-22T05:27:56.948Z"
}