> ## Documentation Index > Fetch the complete documentation index at: https://docs.nonce.app/llms.txt > Use this file to discover all available pages before exploring further. # Create Task Batch > Create a batch task for specified miners with given task type and parameters. Only supports agent specific tasks ## OpenAPI ````yaml /api-reference/openapi.json post /private-api/v1/{workspace_id}/farms/{farm_id}/tasks/batches openapi: 3.1.0 info: title: Nonce Private API description: |- Nonce Private API documentation - Internal endpoints for system integration Generated by NestJS Swagger Module with nestjs-zod Scope: Private API endpoints only (/private-api/*) Do not edit this file manually - regenerate with: pnpm run docs:openapi version: 1.0.0 contact: {} servers: - url: https://api.nonce.app description: Production server security: [] tags: [] paths: /private-api/v1/{workspace_id}/farms/{farm_id}/tasks/batches: post: tags: - Private API - Task summary: Create Task Batch description: >- Create a batch task for specified miners with given task type and parameters. Only supports agent specific tasks operationId: CreateTaskBatch parameters: - name: workspace_id required: true in: path schema: type: string - name: farm_id required: true in: path schema: type: string requestBody: required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/CreateTaskBatch_MinerSystemReboot' title: Reboot - $ref: '#/components/schemas/CreateTaskBatch_MinerLogGet' title: Get Log - $ref: '#/components/schemas/CreateTaskBatch_MinerLightUpdate' title: Update Light Mode - $ref: '#/components/schemas/CreateTaskBatch_MinerMiningModeUpdate' title: Update Mining Mode - $ref: '#/components/schemas/CreateTaskBatch_MinerFirmwareUpdate' title: Update firmware - $ref: '#/components/schemas/CreateTaskBatch_MinerPoolLock' title: Update pool lock - $ref: '#/components/schemas/CreateTaskBatch_AgentScan' title: Agent Scan - $ref: '#/components/schemas/CreateTaskBatch_AgentIpDiagnosis' title: Agent IP Diagnosis - $ref: '#/components/schemas/CreateTaskBatch_AgentSelfUpdate' title: Agent Self Update - $ref: '#/components/schemas/CreateTaskBatch_MinerAssetStatusUpdate' title: Update Miner Asset Status - $ref: '#/components/schemas/CreateTaskBatch_MinerAssetDelete' title: Delete Miners - $ref: '#/components/schemas/CreateTaskBatch_MinerRackLocationUpdate' title: Update Miner Rack Location discriminator: propertyName: task_name mapping: miner.system.reboot: $ref: '#/components/schemas/CreateTaskBatch_MinerSystemReboot' miner.log.get: $ref: '#/components/schemas/CreateTaskBatch_MinerLogGet' miner.light.update: $ref: '#/components/schemas/CreateTaskBatch_MinerLightUpdate' miner.power_mode.update: $ref: '#/components/schemas/CreateTaskBatch_MinerMiningModeUpdate' miner.firmware.update: $ref: '#/components/schemas/CreateTaskBatch_MinerFirmwareUpdate' miner.pool.lock: $ref: '#/components/schemas/CreateTaskBatch_MinerPoolLock' agent.scan.create: $ref: '#/components/schemas/CreateTaskBatch_AgentScan' agent.ip_diagnosis.create: $ref: '#/components/schemas/CreateTaskBatch_AgentIpDiagnosis' agent.self.update: $ref: '#/components/schemas/CreateTaskBatch_AgentSelfUpdate' miner.asset.update: $ref: >- #/components/schemas/CreateTaskBatch_MinerAssetStatusUpdate miner.asset.delete: $ref: '#/components/schemas/CreateTaskBatch_MinerAssetDelete' miner.rack_location.update: $ref: >- #/components/schemas/CreateTaskBatch_MinerRackLocationUpdate responses: '200': description: Successfully created task batches content: application/json: schema: type: object properties: success: type: boolean example: true description: Indicates if the request was successful data: type: array description: Array of items items: type: object properties: batch_id: type: string description: Miner task batch ID example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx task_name: type: string description: Miner task name example: miner.log.get enum: - agent.scan.create - agent.ip_diagnosis.create - agent.self.update - miner.system.reboot - miner.log.get - miner.light.update - miner.power_mode.update - miner.pool.update - miner.pool.lock - miner.firmware.update - miner.asset.update - miner.asset.delete - miner.rack_location.update task_count: type: number description: Number of tasks in the batch example: 10 task_params: description: >- Task parameters (JSON). Structure varies by task_name. additionalProperties: {} type: - object - 'null' created_by: description: >- Represents an entity that performs actions in the system (user, API key, or system) properties: type: type: string enum: - user - apikey - system description: The type of actor example: user id: type: string description: The unique identifier of the actor example: user_2xGz1234567890 name: description: The display name of the actor example: John Doe type: - string - 'null' avatar: description: The avatar URL of the actor example: https://example.com/avatar.png type: - string - 'null' metadata: description: Additional metadata about the actor type: object additionalProperties: {} required: - type - id - name - avatar title: Actor type: - object - 'null' created_at: type: string format: datetime example: YYYY-MM-DDTHH:MM:SSZ description: >- This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ. required: - batch_id - task_name - task_count - task_params - created_by - created_at title: Miner Task Batch error: type: 'null' example: null description: Error object (null on success) meta: type: object properties: summary: type: object properties: created_count: type: number skipped_count: type: number required: - created_count - skipped_count skipped: type: array items: type: object properties: reason: type: string enum: - no_change - unsupported_mode - miner_not_found - unstable_miner description: >- Reason a miner was skipped during task batch creation. `no_change` = miner is already in the requested state; `unsupported_mode` = miner hardware does not support the requested mode; `miner_not_found` = miner id was not found in the workspace or farm; `unstable_miner` = miner row is flagged unstable and cannot accept actions. example: no_change message: type: string miner_ids: type: array items: type: string required: - reason - message - miner_ids required: - summary title: Create Task Batch Meta required: - success - data - error - meta '400': description: Bad Request - Invalid parameters content: application/json: schema: type: object properties: statusCode: type: number description: HTTP status code example: 400 message: type: string description: Error message example: Invalid request parameters error: type: string description: Error type example: Bad Request required: - statusCode - message - error '401': description: Unauthorized - Invalid or missing API key content: application/json: schema: type: object properties: statusCode: type: number description: HTTP status code example: 401 message: type: string description: Error message example: Invalid or missing API key error: type: string description: Error type example: Unauthorized required: - statusCode - message - error '403': description: Forbidden - Valid API key but insufficient permissions content: application/json: schema: type: object properties: statusCode: type: number description: HTTP status code example: 403 message: type: string description: Error message example: Access denied to workspace error: type: string description: Error type example: Forbidden required: - statusCode - message - error '404': description: Not Found - Resource does not exist content: application/json: schema: type: object properties: statusCode: type: number description: HTTP status code example: 404 message: type: string description: Error message example: Resource not found error: type: string description: Error type example: Not Found required: - statusCode - message - error security: - clerk-api-key: [] components: schemas: CreateTaskBatch_MinerSystemReboot: type: object properties: task_name: type: string enum: - miner.system.reboot description: >- Reboot miner ASIC. Brief downtime. Use after firmware update or when miner is unresponsive. miner_ids: minItems: 1 maxItems: 1000 type: array items: type: string description: Array of miner IDs to execute task on params: description: Reboot parameters (optional). type: object properties: force: description: Force reboot (optional) example: false type: boolean additionalProperties: false required: - task_name - miner_ids CreateTaskBatch_MinerLogGet: type: object properties: task_name: type: string enum: - miner.log.get description: >- Collect diagnostic logs from miner ASIC. Dispatches a command to the device; a signed download URL is returned on task success. miner_ids: minItems: 1 maxItems: 1000 type: array items: type: string description: Array of miner IDs to execute task on params: type: object properties: {} additionalProperties: false required: - task_name - miner_ids CreateTaskBatch_MinerLightUpdate: type: object properties: task_name: type: string enum: - miner.light.update description: >- Toggle miner LED indicator. Use for physical identification on the rack. miner_ids: minItems: 1 maxItems: 1000 type: array items: type: string description: Array of miner IDs to execute task on params: type: object properties: mode: type: string enum: - 'on' - 'off' description: >- Miner status LED mode. `on` turns the indicator light on; `off` turns it off. example: 'on' required: - mode additionalProperties: false description: Light mode parameters. required: - task_name - miner_ids - params CreateTaskBatch_MinerMiningModeUpdate: type: object properties: task_name: type: string enum: - miner.power_mode.update description: >- Switch miner mining power mode. Affects hashrate and power consumption. miner_ids: minItems: 1 maxItems: 1000 type: array items: type: string description: Array of miner IDs to execute task on params: type: object properties: mode: anyOf: - type: string enum: - low - normal - high - sleep - J/T 19.0, Hashrate ~125TH/s - J/T 20.0, Hashrate ~135TH/s - J/T 21.0, Hashrate ~145TH/s - J/T 21.5, Hashrate ~155TH/s - J/T 22.0, Hashrate ~165TH/s - J/T 22.5, Hashrate ~170TH/s - J/T 23.0, Hashrate ~175TH/s - 5600W - 5800W - 6000W - 6200W - 6400W - 6600W - type: string minLength: 1 maxLength: 36 description: Mining performance mode level or firmware preset name example: normal required: - mode additionalProperties: false description: Mining mode parameters. required: - task_name - miner_ids - params CreateTaskBatch_MinerFirmwareUpdate: type: object properties: task_name: type: string enum: - miner.firmware.update description: >- Flash firmware to miner. Extended downtime; miner reboots after install. miner_ids: minItems: 1 maxItems: 1000 type: array items: type: string description: Array of miner IDs to execute task on params: type: object properties: firmware_url: type: string format: uri description: URL to the firmware file example: >- https://assets-product.bitmain.com.cn/shop-product-s3/firmware/bfc587e7-b3fb-4568-a5e5-13251308e0ab/2025/01/16/18/Antminer-S21-XP-Hyd.-release-202501061507.bmu required: - firmware_url additionalProperties: false description: Firmware update parameters. required: - task_name - miner_ids - params CreateTaskBatch_MinerPoolLock: type: object properties: task_name: type: string enum: - miner.pool.lock description: >- Lock or unlock miner pool configuration via auth package. Prevents unauthorized pool changes while locked. miner_ids: minItems: 1 maxItems: 1000 type: array items: type: string description: Array of miner IDs to execute task on params: type: object properties: firmware_url: type: string format: uri description: URL to the auth package file example: >- https://storage.example.com/nonce-agent/miners-firmware/agent-id/pool-lock.auth action: type: string enum: - lock - unlock description: Pool lock action example: lock required: - firmware_url - action additionalProperties: false description: Pool lock parameters. required: - task_name - miner_ids - params CreateTaskBatch_AgentScan: type: object properties: task_name: type: string enum: - agent.scan.create description: >- Trigger agent network scan to discover miners. Long-running; populates miner inventory on completion. params: description: Agent scan parameters (optional). type: object properties: ip_ranges: description: >- IP ranges to scan (optional). If omitted, agent scans all configured ranges. type: array items: type: object properties: id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: IP range record ID example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx range: type: string description: IP range in CIDR notation example: 192.168.1.0/24 auto_scan: description: >- Whether to continue scanning this range periodically (optional) example: false type: boolean required: - id - range additionalProperties: false additionalProperties: false required: - task_name CreateTaskBatch_AgentIpDiagnosis: type: object properties: task_name: type: string enum: - agent.ip_diagnosis.create description: >- Trigger agent IP diagnosis and upload a CSV report. Uses local diagnostic context first unless refresh is requested. params: type: object properties: target_scope: default: known_with_custom description: >- Diagnosis target scope. custom_only uses only custom targets; known_with_custom merges agent known IPs and custom targets; known_only uses only agent known IPs. type: string enum: - custom_only - known_with_custom - known_only custom_targets: description: Custom diagnosis targets maxItems: 10000 type: array items: type: object properties: id: description: Optional custom target identifier type: string label: description: Optional custom target label type: string value: type: string pattern: >- ^(?:(?:(25[0-5]|2[0-4]\d|[01]?\d\d?)\.){3}(25[0-5]|2[0-4]\d|[01]?\d\d?)\/(?:3[0-2]|[12]?\d)|(?:(25[0-5]|2[0-4]\d|[01]?\d\d?)\.){3}(25[0-5]|2[0-4]\d|[01]?\d\d?)-(?:(25[0-5]|2[0-4]\d|[01]?\d\d?)\.){3}(25[0-5]|2[0-4]\d|[01]?\d\d?)|(?:(25[0-5]|2[0-4]\d|[01]?\d\d?)\.){3}(25[0-5]|2[0-4]\d|[01]?\d\d?))$ description: IPv4 address, CIDR, or hyphen range to diagnose required: - value additionalProperties: false ping_only: description: >- Only perform ICMP ping checks when the agent probes targets without local context type: boolean additionalProperties: false description: IP diagnosis parameters. required: - task_name - params CreateTaskBatch_AgentSelfUpdate: type: object properties: task_name: type: string enum: - agent.self.update description: >- Trigger agent to self-upgrade to a newer binary. Agent restarts after install; brief control-plane downtime, no miner impact. params: description: >- Agent self-update parameters (optional). All fields default to agent-configured values when omitted. type: object properties: binary_url: description: >- Agent binary download URL (optional). Agent uses its configured default when omitted. type: string md5: description: >- Legacy MD5 checksum of the agent binary (optional). Kept as a supplementary integrity check and not used as the security authority. type: string signature: description: >- Ed25519 detached signature of the agent binary. Required whenever binary_url is provided so the agent can authorize the remote self-update. type: string target_version: description: >- Target agent version (optional). Used by agent to validate upgrade payload. example: v0.4.30 type: string additionalProperties: false required: - task_name CreateTaskBatch_MinerAssetStatusUpdate: type: object properties: task_name: type: string enum: - miner.asset.update description: >- Update miner lifecycle status in inventory. Metadata-only; does not affect mining operation. miner_ids: minItems: 1 maxItems: 1000 type: array items: type: string description: Array of miner IDs to execute task on params: type: object properties: status: type: string enum: - online - on_rack - off_rack - transit - maintenance - retired - archived description: New asset status for the miners example: online comment: description: Optional comment for the status update type: string required: - status additionalProperties: false description: Asset status update parameters. required: - task_name - miner_ids - params CreateTaskBatch_MinerAssetDelete: type: object properties: task_name: type: string enum: - miner.asset.delete description: >- Mark miner as deleted in inventory. Reversible only via database operation. Use after physical decommission. miner_ids: minItems: 1 maxItems: 1000 type: array items: type: string description: Array of miner IDs to execute task on params: description: Asset delete parameters (optional). type: object properties: comment: description: Optional comment for the deletion type: string additionalProperties: false required: - task_name - miner_ids CreateTaskBatch_MinerRackLocationUpdate: type: object properties: task_name: type: string enum: - miner.rack_location.update description: >- Update miner rack / position metadata in inventory. Metadata-only; does not affect mining operation. updates: minItems: 1 maxItems: 100 type: array items: type: object properties: miner_id: type: string rack: anyOf: - type: string maxLength: 50 - type: 'null' description: Rack identifier (up to 50 chars). Null to clear. example: A-12 position: anyOf: - type: integer minimum: 0 maximum: 9007199254740991 - type: 'null' description: >- Slot position within the rack (non-negative integer). Null to clear. example: 3 required: - miner_id - rack - position additionalProperties: false description: >- Per-miner rack location updates. Each entry updates one miner; unchanged miners are omitted from the array. params: type: object properties: {} additionalProperties: false required: - task_name - updates securitySchemes: clerk-api-key: scheme: bearer bearerFormat: API Key type: http description: Clerk Machine API Key for authentication ````