# API reference — Kits

Object kits — customer hardware shipped to the facility, then tracked (mocap markers, mass, mesh scan) and made referenceable from Task Specs as `kit/<name>`. Status: `received → tracked → available`.

## POST /v1/kits

Register an object kit

Register customer hardware for inbound shipping. The response includes the shipping label URL; on arrival the kit is tracked (mocap markers, mass, mesh scan) and becomes referenceable from Task Specs as `kit/<name>`. Kits integrate into the standard fixture/tracking/reset system — the system is never customized around a kit.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| name | body | `string` | yes |  |
| items | body | `array<object>` | yes |  |

Example request:

```json
{
 "name": "acme-breville",
 "items": [
  {
   "desc": "Breville BES870",
   "qty": 1
  }
 ]
}
```

Example response (201):

```json
{
 "id": "kit_acme_breville",
 "object": "kit",
 "name": "acme-breville",
 "status": "registered",
 "status_history": [
  {
   "status": "registered",
   "at": "2026-08-12T10:02:00Z"
  }
 ],
 "items": [
  {
   "desc": "Breville BES870",
   "qty": 1
  }
 ],
 "tracking": null,
 "environment_ref": null,
 "shipping_label_url": "https://api.roborama.com/v1/kits/kit_acme_breville/shipping-label"
}
```

## GET /v1/kits/{kit_id}

Get a kit and its status progression

Status progresses `received → tracked → available`; `status_history` carries the timestamps.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| kit_id | path | `string` | yes |  |

Example response (200):

```json
{
 "id": "kit_acme_breville",
 "object": "kit",
 "name": "acme-breville",
 "status": "available",
 "status_history": [
  {
   "status": "registered",
   "at": "2026-08-12T10:02:00Z"
  },
  {
   "status": "received",
   "at": "2026-08-15T18:30:00Z"
  },
  {
   "status": "tracked",
   "at": "2026-08-17T09:12:00Z"
  },
  {
   "status": "available",
   "at": "2026-08-17T14:45:00Z"
  }
 ],
 "items": [
  {
   "desc": "Breville BES870",
   "qty": 1
  }
 ],
 "tracking": {
  "mocap_markers": 6,
  "mass_g": 10480,
  "mesh_scan": true
 },
 "environment_ref": "kit/acme-breville",
 "shipping_label_url": "https://api.roborama.com/v1/kits/kit_acme_breville/shipping-label"
}
```

## GET /v1/kits/{kit_id}/shipping-label

Get the inbound shipping label

A signed URL for the inbound shipping label PDF.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| kit_id | path | `string` | yes |  |

Example response (200):

```json
{
 "url": "https://artifacts.roborama.com/kits/kit_acme_breville/label.pdf?sig=8f31ab90",
 "expires": "2026-09-08T00:00:00Z"
}
```