Inventory: Kits

Base URL: $BUSINESS_API

List kits and default kits per work-order type

Logs

GET /inventory/kits

Pages the tenant's kits with limit (default 20, max 100) and the after cursor. Filter by work_order_type to find the default kit for a type of work order, and by active. Needs the inventory:read scope.

Parameters

work_order_typestring · query · optional

Kits proposed for one work-order type

activeboolean · query · optional

Only active or inactive kits

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Kits

Show attributes
dataarray of InventoryKit · required
Show child attributes
idstring · required

kit_ identifier

tenant_idstring · required
codestring · required
namestring · required
descriptionstring · optional
work_order_typestring · optional

The work-order type this kit is the default for

activeboolean · required
linesarray of InventoryKitLine · required
Show child attributes
item_idstring · required
quantitynumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

requiredboolean · required

A field order cannot be dispatched until this line is reserved (batch 2)

created_atstring (date-time) · required
updated_atstring (date-time) · required
has_moreboolean · required
next_cursorstring · optional

Errors 400 · 401 · 403

Permissions inventory:read · Roles: admin, analyst, field_reader, field_supervisor, finance, operations, owner, viewer

curl -X GET "$BUSINESS_API/inventory/kits" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "inv_2JVQuPrWedpeyptQQdnuAb9S4dV",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "code": "COD-2026-000142",
      "name": "Ana Matsinhe",
      "description": "Leitura confirmada no local.",
      "work_order_type": "work order type",
      "active": true,
      "lines": [
        {
          "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
          "quantity": 1,
          "required": true
        }
      ],
      "created_at": "2026-11-19T09:30:00Z",
      "updated_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Create a kit

Logs

POST /inventory/kits

Creates a named list of items and quantities that work orders draw on, returned with status 201. code (stored upper case, unique per tenant) and name are required, and lines must hold 1 to 100 distinct existing items with positive quantities, in whole units for serialised items. Setting work_order_type makes the kit the default for that type; 409 when another active kit already holds that type or the code exists. Needs the inventory:supervise scope; send an Idempotency-Key header to make retries safe.

Parameters

Idempotency-Keystring · header · optional

Makes an inventory write safe to retry, for field issues replayed from offline phones. 1 to 255 visible ASCII characters, scoped to the tenant and endpoint and kept for 30 days. A completed write is stored with its response in the same transaction and returned again with its original status and body and the header Idempotent-Replayed: true, recording nothing twice. The same key on a different request (body, path or caller) is refused with 409 idempotency_conflict. A refusal is never stored.

Body application/json

codestring · required
namestring · required
descriptionstring · optional
work_order_typestring · optional
linesarray of InventoryKitLine · required
Show child attributes
item_idstring · required
quantitynumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

requiredboolean · required

A field order cannot be dispatched until this line is reserved (batch 2)

Returns

201 Kit created

Show attributes
idstring · required

kit_ identifier

tenant_idstring · required
codestring · required
namestring · required
descriptionstring · optional
work_order_typestring · optional

The work-order type this kit is the default for

activeboolean · required
linesarray of InventoryKitLine · required
Show child attributes
item_idstring · required
quantitynumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

requiredboolean · required

A field order cannot be dispatched until this line is reserved (batch 2)

created_atstring (date-time) · required
updated_atstring (date-time) · required

Errors 400 · 401 · 403 · 404 · 409

Permissions inventory:supervise · Roles: admin, operations, owner

curl -X POST "$BUSINESS_API/inventory/kits" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "code": "COD-2026-000142",
  "name": "Ana Matsinhe",
  "description": "Leitura confirmada no local.",
  "work_order_type": "work order type",
  "lines": [
    {
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "quantity": 1,
      "required": true
    }
  ]
}'
Response 201
{
  "id": "inv_2JVQuPrWedpeyptQQdnuAb9S4dV",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "code": "COD-2026-000142",
  "name": "Ana Matsinhe",
  "description": "Leitura confirmada no local.",
  "work_order_type": "work order type",
  "active": true,
  "lines": [
    {
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "quantity": 1,
      "required": true
    }
  ],
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Get a kit

Logs

GET /inventory/kits/{id}

Returns one kit of the caller's tenant with its lines and the work-order type it is the default for. Returns 404 when the kit does not exist in this tenant. Needs the inventory:read scope.

Parameters

idstring · path · required

Kit ID (kit_)

Returns

200 Kit

Show attributes
idstring · required

kit_ identifier

tenant_idstring · required
codestring · required
namestring · required
descriptionstring · optional
work_order_typestring · optional

The work-order type this kit is the default for

activeboolean · required
linesarray of InventoryKitLine · required
Show child attributes
item_idstring · required
quantitynumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

requiredboolean · required

A field order cannot be dispatched until this line is reserved (batch 2)

created_atstring (date-time) · required
updated_atstring (date-time) · required

Errors 401 · 403 · 404

Permissions inventory:read · Roles: admin, analyst, field_reader, field_supervisor, finance, operations, owner, viewer

curl -X GET "$BUSINESS_API/inventory/kits/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "id": "inv_2JVQuPrWedpeyptQQdnuAb9S4dV",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "code": "COD-2026-000142",
  "name": "Ana Matsinhe",
  "description": "Leitura confirmada no local.",
  "work_order_type": "work order type",
  "active": true,
  "lines": [
    {
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "quantity": 1,
      "required": true
    }
  ],
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Change a kit or its lines

Logs

PATCH /inventory/kits/{id}

Changes only the fields you send: name, description, work_order_type, active, and lines (replaces all lines, with the same rules as on create). An active kit keeps the one-default-per-type rule, so naming a work-order type that another active kit already holds returns 409. Needs the inventory:supervise scope; send an Idempotency-Key header to make retries safe.

Parameters

idstring · path · required

Kit ID (kit_)

Idempotency-Keystring · header · optional

Makes an inventory write safe to retry, for field issues replayed from offline phones. 1 to 255 visible ASCII characters, scoped to the tenant and endpoint and kept for 30 days. A completed write is stored with its response in the same transaction and returned again with its original status and body and the header Idempotent-Replayed: true, recording nothing twice. The same key on a different request (body, path or caller) is refused with 409 idempotency_conflict. A refusal is never stored.

Body application/json

namestring · optional
descriptionstring · optional
work_order_typestring · optional
activeboolean · optional
linesarray of InventoryKitLine · optional

Replaces the kit's lines.

Show child attributes
item_idstring · required
quantitynumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

requiredboolean · required

A field order cannot be dispatched until this line is reserved (batch 2)

Returns

200 Kit updated

Show attributes
idstring · required

kit_ identifier

tenant_idstring · required
codestring · required
namestring · required
descriptionstring · optional
work_order_typestring · optional

The work-order type this kit is the default for

activeboolean · required
linesarray of InventoryKitLine · required
Show child attributes
item_idstring · required
quantitynumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

requiredboolean · required

A field order cannot be dispatched until this line is reserved (batch 2)

created_atstring (date-time) · required
updated_atstring (date-time) · required

Errors 400 · 401 · 403 · 404 · 409

Permissions inventory:supervise · Roles: admin, operations, owner

curl -X PATCH "$BUSINESS_API/inventory/kits/{id}" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Ana Matsinhe",
  "description": "Leitura confirmada no local.",
  "work_order_type": "work order type",
  "active": true,
  "lines": [
    {
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "quantity": 1,
      "required": true
    }
  ]
}'
Response 200
{
  "id": "inv_2JVQuPrWedpeyptQQdnuAb9S4dV",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "code": "COD-2026-000142",
  "name": "Ana Matsinhe",
  "description": "Leitura confirmada no local.",
  "work_order_type": "work order type",
  "active": true,
  "lines": [
    {
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "quantity": 1,
      "required": true
    }
  ],
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}