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

Request a pre-signed upload URL:

mutation GetUploadUrl($objectType: String!, $objectId: uuid!, $filename: String!) {
  generateUploadUrl(input: {
    objectType: $objectType,
    objectId: $objectId,
    filename: $filename
  }) {
    uploadUrl
    expiresAt
  }
}

Upload the file to the pre-signed URL using HTTP PUT

Download Attachment

Request a pre-signed download URL:

mutation GetDownloadUrl($objectType: String!, $objectId: uuid!, $filename: String!) {
  generateDownloadUrl(input: {
    objectType: $objectType,
    objectId: $objectId,
    filename: $filename
  }) {
    downloadUrl
    expiresAt
  }
}

Security

Pre-signed URLs are short-lived. Request a new URL each time you need to access a file.

User Management

(Available to Organization Manager role)

Create User

mutation CreateUser($email: String!, $role: String!, $organizationId: uuid!) {
  insertUser(object: {
    email: $email,
    role: $role,
    organizationId: $organizationId
  }) {
    id
    email
    role
    createdAt
  }
}

Update User Role

mutation UpdateUserRole($userId: uuid!, $role: String!) {
  updateUser(pk_columns: {id: $userId}, _set: {role: $role}) {
    id
    email
    role
    updatedAt
  }
}

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