Task Management

Overview

BitRobot tracks robot operations through tasks and task runs. A task represents a type of operation your robots perform, while task runs are individual executions of those tasks. Each run follows three steps:

Start — call task_start when a robot begins an operation. BitRobot creates a task run and returns a task_run_id.
End — call task_end when the operation completes. Provide a raw_data_uri pointing to the run’s output and a raw_data_cid for integrity verification; BitRobot records the run on-chain and verifies the file before validation.
Validate — call task_validate to award VRW points to the resource owner based on the run’s output.

Task lifecycle flowchart

Event Types

Register Resource

POST /subnets/{subnet_id}/events
{
  "event_type": "register_resource",
  "resource_name": "bot_001",
  "resource_subtype": "frodobot",
  "owner": "HN7cABqLq46Es1jh92dQQisAq662SmxELLLsHHe4YWrH",
  "ent_metadata": {
    "name": "Frodobot #001",
    "symbol": "FRODO",
    "description": "Autonomous delivery robot",
    "image": "https://example.com/images/frodobot-001.png"
  }
}

The response includes a resource_id and ent_address (the on-chain PDA of the created ENT). Store the resource_id to use in subsequent task_start events instead of repeating resource_name, resource_subtype, and ENT fields:

{
  "status": "success",
  "data": {
    "resource_id": "01ARZ3NDEKTSV4RRFFQ69G5FAY",
    "ent_address": "4uQeVj5tqViQh7yWWGStvkEG1Zmhx6uasJtWCJziofM"
  }
}

Task Start

Start a new task run when a robot begins an operation. task_id is optional — if your subnet has exactly one task, it will be used automatically. If your subnet has multiple tasks, you must specify which one to use. You can optionally supply your own task_run_id (ULID format) to identify the run. If you don’t provide one, the API will generate one for you — note it from the response so you can use it when ending the run.

POST /subnets/{subnet_id}/events
{
  "event_type": "task_start",
  "event_id": "ride_123456",
  "resource_name": "bot_001",
  "resource_subtype": "frodobot",
  "started_at": "2024-01-15T10:30:00Z",
  "ent_owner": "HN7cABqLq46Es1jh92dQQisAq662SmxELLLsHHe4YWrH",
  "ent_metadata": {
    "name": "Frodobot #001",
    "symbol": "FRODO",
    "description": "Autonomous delivery robot",
    "image": "https://example.com/images/frodobot-001.png"
  }
}

If your subnet has multiple tasks, specify which one to use:

POST /subnets/{subnet_id}/events
{
  "event_type": "task_start",
  "task_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "event_id": "ride_123456",
  "resource_name": "bot_001",
  "resource_subtype": "frodobot",
  "started_at": "2024-01-15T10:30:00Z",
  "ent_owner": "HN7cABqLq46Es1jh92dQQisAq662SmxELLLsHHe4YWrH",
  "ent_metadata": {
    "name": "Frodobot #001",
    "symbol": "FRODO",
    "description": "Autonomous delivery robot",
    "image": "https://example.com/images/frodobot-001.png"
  }
}

event_id

event_id is a required, caller-defined identifier for the event. It must be unique within a given task — submitting a second task_start with the same event_id against the same task_id returns an error. You can use it to associate the task run with a record in your own system, or supply any unique string.

started_at

started_at is an optional ISO 8601 timestamp recording when the robot actually began the operation. Use this when you want to capture the real-world start time, which may differ from when the event was ingested by BitRobot. The response includes task_id, task_run_id, and the resource_id of the resource the run was attached to (created on the fly if it didn’t already exist). You will need the task_run_id to end the run:

{
  "status": "success",
  "data": {
    "task_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "task_run_id": "01BXC4MDEKTSV4RRFFQ69G5FBW",
    "resource_id": "01ARZ3NDEKTSV4RRFFQ69G5FAY"
  }
}

ENT ownership

Each resource has an on-chain ENT (Entity NFT) — a Solana NFT that represents ownership of the robot and entitles its holder to token rewards. When identifying a resource by resource_name/resource_subtype, ent_owner is required and ent_metadata is recommended:

POST /subnets/{subnet_id}/events
{
  "event_type": "task_start",
  "event_id": "ride_123456",
  "resource_name": "bot_001",
  "resource_subtype": "frodobot",
  "ent_owner": "HN7cABqLq46Es1jh92dQQisAq662SmxELLLsHHe4YWrH",
  "ent_metadata": {
    "name": "Frodobot #001",
    "symbol": "FRODO",
    "description": "Autonomous delivery robot",
    "image": "https://example.com/images/frodobot-001.png"
  }
}

ent_owner — the Solana wallet address that will own the ENT and receive token rewards for this resource. Required when using resource_name/resource_subtype; can be omitted when using resource_id (the ENT already exists on-chain).
ent_metadata — metadata for the NFT, following the Metaplex token standard. Optional — if omitted, a placeholder URI is used.

ENT creation is idempotent — if the resource already has an on-chain ENT, these fields are ignored. Alternatively, you can provision the ENT upfront via a register_resource event using the owner and ent_metadata fields, before any task runs occur.

Task End

Complete a task run using the task_run_id returned from the task_start response. Include a raw_data_uri pointing to the raw output of the run — typically a video, but any file type is supported — and a raw_data_cid: the IPFS CID of the file, computed locally before upload. Compute the CID using the Kubo CLI:

# First time only, initialize the local IPFS repo:
ipfs init

ipfs add -n --raw-leaves --chunker=size-1048576 -Q /path/to/task_run_123.mp4
# QmNZNUx3scL8WvGzXy6bsbTZPACBL17HURMZmGsG5HavYB

The CID is printed to stdout. Include it in the event alongside the URI. You can also pass ended_at to record the real-world time the operation finished:

POST /subnets/{subnet_id}/events
{
  "event_type": "task_end",
  "task_run_id": "01BXC4MDEKTSV4RRFFQ69G5FBW",
  "raw_data_uri": "https://example.com/data/task_run_123.mp4",
  "raw_data_cid": "QmNZNUx3scL8WvGzXy6bsbTZPACBL17HURMZmGsG5HavYB",
  "ended_at": "2024-01-15T10:45:00Z"
}

The task_end event is recorded immediately and the run is ended on-chain. BitRobot then asynchronously downloads the file at raw_data_uri, recomputes the CID using ipfs add -n --raw-leaves --chunker=size-1048576 -Q, and verifies the result matches raw_data_cid. If verification passes, the file is stored and the run is eligible for validation. If verification fails, the run is marked as invalid and task_validate will return an error.

The URI must be publicly accessible when the event is processed. Use exactly ipfs add -n --raw-leaves --chunker=size-1048576 -Q to compute raw_data_cid — other tools or flags may produce a different CID for the same file, causing verification to fail.

Task Validate

After a task run ends, validate it and award VRW (Verifiable Robotic Work) points to the resource. Use the task_run_id from the task_start response:

POST /subnets/{subnet_id}/events
{
  "event_type": "task_validate",
  "task_run_id": "01BXC4MDEKTSV4RRFFQ69G5FBW",
  "vrw_points": 120
}

The vrw_points value determines how many on-chain VRW points are awarded to the resource owner for this run. These points are used for proportional token reward distribution at the end of each epoch.

By default, validating a run also grants the resource owner Subnet Points equal to vrw_points (in addition to the on-chain VRW). A subnet can turn this off with the auto_grant_subnet_points_from_vrw setting — when it’s off, validation records VRW on-chain but grants no Subnet Points, leaving distribution to the subnet. See Automatic grants from VRW.

Batch Upload

If you have historical task run data or want to import runs in bulk, you can upload a CSV file instead of sending individual events. Each row is processed through the same start → end → validate flow as individual events.

Upload a CSV

POST /subnets/{subnet_id}/task_batch_uploads
Content-Type: multipart/form-data

csv_file=@task_runs.csv

The response returns a batch ID you can use to poll for progress:

{
  "id": "01ARZ3NDEKTSV4RRFFQ69G5FAZ",
  "queued": 42,
  "failed": 1
}

queued is the number of rows accepted for processing. failed is the number of rows that were rejected due to validation errors — these are recorded in the batch and visible when you poll for status.

CSV format

Each row represents one complete task run. Required columns:

Column	Required	Description
`event_id`	Yes	Unique identifier for this run — used as an idempotency key
`vrw_points`	Yes	VRW points to award on validation (>= 0)
`resource_id`	Yes*	ID of an existing resource
`resource_name`	Yes*	Name of the resource
`resource_subtype`	Yes*	Subtype of the resource (e.g. `frodobot`)
`resource_type`	Yes*	`ent` for full ENT NFT resources, or `resource` for lightweight non-NFT participants. Required when `resource_id` is not provided
`ent_owner`	Yes*	Solana wallet address that owns the ENT
`task_id`	No	Task to associate the run with. If omitted, falls back to auto-resolution (same as individual events)
`started_at`	Yes	ISO 8601 timestamp for when the run started
`ended_at`	Yes	ISO 8601 timestamp for when the run ended
`raw_data_uri`	Yes	URI of the run’s raw output data
`raw_data_cid`	Yes	IPFS CID of the raw output file, computed with `ipfs add -n --raw-leaves --chunker=size-1048576 -Q`

* Provide either resource_id alone, or resource_name + resource_subtype + resource_type + ent_owner together. Example CSV:

event_id,resource_name,resource_subtype,resource_type,ent_owner,vrw_points,started_at,ended_at,raw_data_uri,raw_data_cid
ride_001,bot_001,frodobot,ent,HN7cABqLq46Es1jh92dQQisAq662SmxELLLsHHe4YWrH,100,2024-01-15T10:30:00Z,2024-01-15T10:45:00Z,https://example.com/data/ride_001.mp4,QmNZNUx3scL8WvGzXy6bsbTZPACBL17HURMZmGsG5HavYB
ride_002,bot_002,frodobot,ent,HN7cABqLq46Es1jh92dQQisAq662SmxELLLsHHe4YWrH,85,2024-01-15T11:00:00Z,2024-01-15T11:12:00Z,https://example.com/data/ride_002.mp4,QmTzQ1Njk27zX5mW4c9J2vX4x6mS7cP9W8xY6pQ3rT2uAa

Poll batch status

Use the batch ID to check progress:

GET /subnets/{subnet_id}/task_batch_uploads/{batch_id}

{
  "id": "01ARZ3NDEKTSV4RRFFQ69G5FAZ",
  "status": "processing",
  "total": 43,
  "pending": 12,
  "processing": 3,
  "completed": 27,
  "failed": 1,
  "rows": [
    {
      "row_number": 2,
      "event_id": "ride_001",
      "status": "completed",
      "task_run_id": "01BXC4MDEKTSV4RRFFQ69G5FBW",
      "error_message": null,
      "steps": {
        "create_task_run": { "status": "completed", "error_message": null },
        "start_run": { "status": "completed", "error_message": null },
        "complete_task_run": { "status": "completed", "error_message": null },
        "end_run": { "status": "completed", "error_message": null },
        "validate_run": { "status": "completed", "error_message": null }
      }
    },
    {
      "row_number": 3,
      "event_id": "ride_002",
      "status": "failed",
      "task_run_id": null,
      "error_message": "Resource not found with id: 01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "steps": {
        "create_task_run": { "status": "failed", "error_message": "Resource not found with id: 01ARZ3NDEKTSV4RRFFQ69G5FAV" },
        "start_run": { "status": "pending", "error_message": null },
        "complete_task_run": { "status": "pending", "error_message": null },
        "end_run": { "status": "pending", "error_message": null },
        "validate_run": { "status": "pending", "error_message": null }
      }
    }
  ]
}

status is processing while any rows are still pending or in progress, and completed once all rows have finished (whether successfully or not). Each row has one of four statuses:

Status	Meaning
`pending`	Queued, not yet started
`processing`	Currently running
`completed`	Successfully processed — `task_run_id` is set
`failed`	Processing failed — `error_message` explains why

The steps object breaks the row down into the five stages of the start → end → validate pipeline (create_task_run, start_run, complete_task_run, end_run, validate_run). Each step carries its own status (same enum as the row) and error_message. Use this to see which stage failed when a row’s top-level status is failed. Both endpoints accept either a subnet API key (recommended for server-to-server use) or a subnet-admin JWT from the BitRobot dashboard.

Subnet admins can view task runs through the Task Management page in the BitRobot dashboard:

Task Runs History: See all task runs with status, type, and timestamps
Summary Stats: View total runs, unique tasks, and unique resources
Filtering and Sorting: Sort by date to find specific task runs

API Reference

View the full events API reference

​Overview

​Event Types

​Register Resource

​Task Start

​event_id

​started_at

​ENT ownership

​Task End

​Task Validate

​Batch Upload

​Upload a CSV

​CSV format

​Poll batch status

​Task Management

API Reference

Overview

Event Types

Register Resource

Task Start

event_id

started_at

ENT ownership

Task End

Task Validate

Batch Upload

Upload a CSV

CSV format

Poll batch status

Task Management