Mutations

GraphQL mutations for device configuration and management

Overview

Mutations allow you to create, update, and delete resources in Haltian IoT. Available mutations depend on your user role.

Note

The complete mutation API is available via GraphQL introspection. Use Postman or Apollo CLI to explore available mutations for your role.

Device Management

Update Device Name

mutation UpdateDeviceName($id: uuid!, $name: String!) {
  updateDevice(pk_columns: {id: $id}, _set: {name: $name}) {
    id
    name
    updatedAt
  }
}

Assign Device to Space

mutation AssignDeviceToSpace($deviceId: uuid!, $spaceId: uuid!) {
  updateDevice(pk_columns: {id: $deviceId}, _set: {spaceId: $spaceId}) {
    id
    spaceId
    updatedAt
  }
}

Space Management

Create Space

mutation CreateSpace($name: String!, $spaceType: String!, $parentId: uuid, $organizationId: uuid!) {
  insertSpace(object: {
    name: $name,
    spaceType: $spaceType,
    parentId: $parentId,
    organizationId: $organizationId
  }) {
    id
    name
    spaceType
    createdAt
  }
}

Update Space

mutation UpdateSpace($id: uuid!, $name: String!) {
  updateSpace(pk_columns: {id: $id}, _set: {name: $name}) {
    id
    name
    updatedAt
  }
}

Asset Management

Create Asset

mutation CreateAsset($name: String!, $assetType: String!, $spaceId: uuid!) {
  insertAsset(object: {
    name: $name,
    assetType: $assetType,
    spaceId: $spaceId
  }) {
    id
    name
    assetType
    createdAt
  }
}

Assign Device to Asset

mutation AssignDeviceToAsset($assetId: uuid!, $deviceId: uuid!) {
  insertAssetDevice(object: {
    assetId: $assetId,
    deviceId: $deviceId
  }) {
    assetId
    deviceId
  }
}

File Attachments

Haltian IoT API supports file attachments for various objects.

Attachment Types

Object	Use Case
Device	Installation images, videos
Asset	Thumbnail, avatar
Space	Floorplan images
Organization	Logo

Upload Attachment

Upload a file attachment directly to an object:

mutation UploadAttachment(
  $objectType: String!,
  $objectId: String!,
  $fileName: String!,
  $file: String!,
  $contentType: String,
  $description: String
) {
  uploadFileAttachment(uploadFileAttachmentInput: {
    objectType: $objectType,
    objectId: $objectId,
    fileName: $fileName,
    file: $file,
    contentType: $contentType,
    description: $description
  })
}

The mutation returns the UUID of the created attachment.

Input Field	Type	Required	Description
`objectType`	String	Yes	Type of object (e.g., “device”, “asset”, “space”)
`objectId`	String	Yes	UUID of the parent object
`fileName`	String	Yes	Name of the file
`file`	String	Yes	Base64 encoded file content
`contentType`	String	No	MIME type of the file
`description`	String	No	Optional description

User Management

(Available to Organization Manager role)

Create User

mutation CreateUser($email: String!, $organizationId: String, $password: String) {
  createUser(createUserInput: {
    email: $email,
    organizationId: $organizationId,
    password: $password
  }) {
    id
    email
    organizationId
    createdAt
  }
}

Input Field	Type	Required	Description
`email`	String	Yes	User’s email address
`organizationId`	String	No	Organization to assign user to
`password`	String	No	Initial password (auto-generated if not provided)

Delete User

mutation DeleteUser($userId: String!) {
  deleteUser(deleteUserInput: {
    userId: $userId
  }) {
    message
  }
}

Change User Password

mutation ChangePassword($currentPassword: String!, $newPassword: String!) {
  changeUserPassword(changeUserPasswordInput: {
    currentPassword: $currentPassword,
    newPassword: $newPassword
  }) {
    message
  }
}

Integration & API Key Management

Manage MQTT streaming integrations and API keys programmatically. For a complete step-by-step walkthrough, see the MQTT API Key Management Guide.

Create MQTT Subscription Integration

mutation CreateMqttIntegration($description: String) {
  createMqttSubscriptionIntegration(object: {
    description: $description,
    mqttSubscriptionState: "active"
  }) {
    id
    description
    mqttSubscriptionState
    organizationId
    createdAt
    updatedAt
  }
}

Create API Key

The token is only returned at creation time and expires after 90 days.

mutation CreateApiKey($name: String!) {
  createApiKey(createApiKeyInput: {
    name: $name
  }) {
    id
    name
    organizationId
    createdAt
    token {
      token
      issuedAt
      expiresAt
    }
  }
}

Assign API Key Role

mutation AssignApiKeyRole($apiKeyId: uuid!) {
  assignApiKeyOrganizationRole(object: {
    roleName: "MqttIntegrator",
    apiKeyId: $apiKeyId
  }) {
    apiKeyId
    roleName
    organizationId
  }
}

Link API Key to MQTT Integration

mutation AssignApiKeyToMqttIntegration($mqttSubscriptionId: uuid!, $apiKeyId: uuid!) {
  assignMqttSubscriptionIntegrationApiKey(object: {
    mqttSubscriptionId: $mqttSubscriptionId,
    apiKeyId: $apiKeyId
  }) {
    mqttSubscriptionId
    apiKeyId
  }
}

Refresh API Key Token

Regenerate the token before the 90-day expiration. The key ID stays the same.

mutation RefreshApiKey($apiKeyId: uuid!) {
  refreshApiKeyToken(refreshApiKeyTokenInput: {
    apikeyId: $apiKeyId
  }) {
    id
    organizationId
    token {
      token
      issuedAt
      expiresAt
    }
  }
}

Delete API Key

mutation DeleteApiKey($apiKeyId: uuid!) {
  deleteApiKey(deleteApiKeyInput: {
    apikeyId: $apiKeyId
  }) {
    message
  }
}

Best Practices

Validate inputs before submitting mutations
Handle errors gracefully - check for validation errors in the response
Use transactions when multiple related changes are needed
Refresh data after mutations to ensure UI consistency
Log changes for audit purposes

Role-Based Access

Mutation availability depends on your role:

Role	Available Mutations
Manager	All mutations
Designer	Space and asset management
Installer	Device assignment, limited updates
Viewer	None (read-only)

Next Steps

Authentication - Token management
Queries - Read data from the API