Topolo Docs Topolo Platform
Open workspace

Get Inventory item

Read one item in the granted workspace with descriptive fields, archive status and quantityOnHand computed from all its movements. Archived items remain readable; missing or foreign items return not_found.

Outcome

Read one item in the granted workspace with descriptive fields, archive status and quantityOnHand computed from all its movements. Archived items remain readable; missing or foreign items return not_found.

Before you start

  • Verify the authenticated identity, exact environment and pinned approved organization context before preparing an action.
  • The published application permission is workspace:read. Discover a granted Inventory workspace and bind that exact resource. Supplied identifiers do not grant access.

Discover the target

topolo whoami --json
topolo actions get app_topolo_inventory.items.get --detail --json
topolo resources topolo-inventory --json
topolo workspaces list topolo-inventory --json
  • Select the exact granted workspace id as INVENTORY_WORKSPACE_ID. Fixture ids authorize no live operation.
  • Discover item ids through items.list or the reviewed items.create response in this workspace.

Request

GET /api/items/{itemId}

Save action input as payload.json. Inspect the plan for the exact path, query and body. Set INVENTORY_WORKSPACE_ID from granted resource discovery.

Inspect and test this action in the signed action console, then perform the verification below.

Input fields

FieldRequiredTypeConstraints
itemIdRequiredstringExisting item id returned by items.list or items.create in this exact workspace.; {"minLength":1}

View the complete input schema in the action console. The same schema is available through CLI and MCP action discovery.

Effects

  • Reads one organization/workspace-scoped item and sums its ledger across all locations and review statuses without changing records.

Interpret the response

Use response path $.item.id for inventory_item. An empty list does not discover a target.

Match item.id and workspaceId to the discovered target. Check quantityOnHand, status and threshold; review decisions do not reverse recorded deltas.

The success schema was checked against captured handler responses. Delegated Auth profile and canonical widget context fields can vary; exact Inventory projections and all six raw SQL export stores are source-reviewed. Error examples retain their actual refusal shapes.

View the complete success schema in the action console. The worked examples below retain complete captured responses; action discovery supplies the exact schema.

Worked examples

Captured exported Worker responses use both real local SQLite D1 databases with all six committed migrations, synthetic Auth/workspace grants and simulated Notify/Nexus/archive transport. They prove local handler shapes and scoped behavior, not live authorization, notification delivery, metering acceptance or environment deployment. Large 100-row list/capped-dashboard captures are retained in local evidence; committed tests verify those limits while worked guides use smaller complete responses. Refused examples demonstrate boundaries and must not be executed as successful workflows.

Successful request

Actual exported Worker response with both local SQLite D1 databases and all committed migrations; synthetic Auth/grants and simulated Notify/Nexus/archive transport. No live delivery, billing or environment deployment proof. Captured scenario: archived item remains readable.

Input · payload.json:

{
  "itemId": "invitem_b29c4494-14e0-43dd-87e6-e33856f732af"
}

CLI:

topolo actions validate app_topolo_inventory.items.get --data @payload.json --json
topolo actions plan app_topolo_inventory.items.get --resource-type workspace --resource-id "$INVENTORY_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_inventory.items.get --resource-type workspace --resource-id "$INVENTORY_WORKSPACE_ID" --data @payload.json --json

MCP tool and arguments:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_inventory.items.get",
    "input": {
      "itemId": "invitem_b29c4494-14e0-43dd-87e6-e33856f732af"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>"
  }
}

Captured local response · HTTP 200:

{
  "item": {
    "id": "invitem_b29c4494-14e0-43dd-87e6-e33856f732af",
    "workspaceId": "ws_inventory_fixture",
    "sku": "KRAFT-MAILER-240X320",
    "name": "Kraft mailer 240x320",
    "description": "",
    "unit": "unit",
    "status": "archived",
    "lowStockThreshold": 0,
    "quantityOnHand": 0,
    "createdByUserId": "usr_inventory_fixture",
    "createdByEmail": "operator@example.test",
    "createdAt": "2026-10-04T05:46:36.190Z",
    "updatedAt": "2026-10-04T05:46:36.270Z"
  }
}

HTTP 200. Match item.id and workspaceId to the discovered target. Check quantityOnHand, status and threshold; review decisions do not reverse recorded deltas.

Another supported request

Actual exported Worker response with both local SQLite D1 databases and all committed migrations; synthetic Auth/grants and simulated Notify/Nexus/archive transport. No live delivery, billing or environment deployment proof. Captured scenario: import preserved existing item id.

Input · payload.json:

{
  "itemId": "invitem_1b7ebfd7-0d3d-4130-a550-2dc160b0e80a"
}

CLI:

topolo actions validate app_topolo_inventory.items.get --data @payload.json --json
topolo actions plan app_topolo_inventory.items.get --resource-type workspace --resource-id "$INVENTORY_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_inventory.items.get --resource-type workspace --resource-id "$INVENTORY_WORKSPACE_ID" --data @payload.json --json

MCP tool and arguments:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_inventory.items.get",
    "input": {
      "itemId": "invitem_1b7ebfd7-0d3d-4130-a550-2dc160b0e80a"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>"
  }
}

Captured local response · HTTP 200:

{
  "item": {
    "id": "invitem_1b7ebfd7-0d3d-4130-a550-2dc160b0e80a",
    "workspaceId": "ws_inventory_fixture",
    "sku": "WIDGET-BLUE",
    "name": "Renamed widget",
    "description": "",
    "unit": "box",
    "status": "active",
    "lowStockThreshold": 7,
    "quantityOnHand": 0,
    "createdByUserId": "usr_inventory_fixture",
    "createdByEmail": "operator@example.test",
    "createdAt": "2026-10-04T05:46:37.690Z",
    "updatedAt": "2026-10-04T05:46:37.755Z"
  }
}

HTTP 200. Match item.id and workspaceId to the discovered target. Check quantityOnHand, status and threshold; review decisions do not reverse recorded deltas.

Another supported request

Actual exported Worker response with both local SQLite D1 databases and all committed migrations; synthetic Auth/grants and simulated Notify/Nexus/archive transport. No live delivery, billing or environment deployment proof. Captured scenario: items.get.

Input · payload.json:

{
  "itemId": "invitem_b29c4494-14e0-43dd-87e6-e33856f732af"
}

CLI:

topolo actions validate app_topolo_inventory.items.get --data @payload.json --json
topolo actions plan app_topolo_inventory.items.get --resource-type workspace --resource-id "$INVENTORY_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_inventory.items.get --resource-type workspace --resource-id "$INVENTORY_WORKSPACE_ID" --data @payload.json --json

MCP tool and arguments:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_inventory.items.get",
    "input": {
      "itemId": "invitem_b29c4494-14e0-43dd-87e6-e33856f732af"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>"
  }
}

Captured local response · HTTP 200:

{
  "item": {
    "id": "invitem_b29c4494-14e0-43dd-87e6-e33856f732af",
    "workspaceId": "ws_inventory_fixture",
    "sku": "KRAFT-MAILER-240X320",
    "name": "Kraft mailer 240x320",
    "description": "",
    "unit": "unit",
    "status": "active",
    "lowStockThreshold": 0,
    "quantityOnHand": 0,
    "createdByUserId": "usr_inventory_fixture",
    "createdByEmail": "operator@example.test",
    "createdAt": "2026-10-04T05:46:36.190Z",
    "updatedAt": "2026-10-04T05:46:36.190Z"
  }
}

HTTP 200. Match item.id and workspaceId to the discovered target. Check quantityOnHand, status and threshold; review decisions do not reverse recorded deltas.

Another supported request

Actual exported Worker response with both local SQLite D1 databases and all committed migrations; synthetic Auth/grants and simulated Notify/Nexus/archive transport. No live delivery, billing or environment deployment proof. Captured scenario: negative stock is permitted.

Input · payload.json:

{
  "itemId": "invitem_e5b77ab2-fc66-43fa-a80c-9583d66a0ccb"
}

CLI:

topolo actions validate app_topolo_inventory.items.get --data @payload.json --json
topolo actions plan app_topolo_inventory.items.get --resource-type workspace --resource-id "$INVENTORY_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_inventory.items.get --resource-type workspace --resource-id "$INVENTORY_WORKSPACE_ID" --data @payload.json --json

MCP tool and arguments:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_inventory.items.get",
    "input": {
      "itemId": "invitem_e5b77ab2-fc66-43fa-a80c-9583d66a0ccb"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>"
  }
}

Captured local response · HTTP 200:

{
  "item": {
    "id": "invitem_e5b77ab2-fc66-43fa-a80c-9583d66a0ccb",
    "workspaceId": "ws_inventory_fixture",
    "sku": "WIDGET-BLUE",
    "name": "Blue widget",
    "description": "",
    "unit": "unit",
    "status": "active",
    "lowStockThreshold": 5,
    "quantityOnHand": -103,
    "createdByUserId": "usr_inventory_fixture",
    "createdByEmail": "operator@example.test",
    "createdAt": "2026-10-04T05:46:38.618Z",
    "updatedAt": "2026-10-04T05:46:38.618Z"
  }
}

HTTP 200. Match item.id and workspaceId to the discovered target. Check quantityOnHand, status and threshold; review decisions do not reverse recorded deltas.

Another supported request

Actual exported Worker response with both local SQLite D1 databases and all committed migrations; synthetic Auth/grants and simulated Notify/Nexus/archive transport. No live delivery, billing or environment deployment proof. Captured scenario: pending movement already affects quantity.

Input · payload.json:

{
  "itemId": "invitem_cf12df06-7056-4441-bef4-95d5c15ef1ed"
}

CLI:

topolo actions validate app_topolo_inventory.items.get --data @payload.json --json
topolo actions plan app_topolo_inventory.items.get --resource-type workspace --resource-id "$INVENTORY_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_inventory.items.get --resource-type workspace --resource-id "$INVENTORY_WORKSPACE_ID" --data @payload.json --json

MCP tool and arguments:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_inventory.items.get",
    "input": {
      "itemId": "invitem_cf12df06-7056-4441-bef4-95d5c15ef1ed"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>"
  }
}

Captured local response · HTTP 200:

{
  "item": {
    "id": "invitem_cf12df06-7056-4441-bef4-95d5c15ef1ed",
    "workspaceId": "ws_inventory_fixture",
    "sku": "WIDGET-BLUE",
    "name": "Blue widget",
    "description": "",
    "unit": "unit",
    "status": "active",
    "lowStockThreshold": 5,
    "quantityOnHand": 10,
    "createdByUserId": "usr_inventory_fixture",
    "createdByEmail": "operator@example.test",
    "createdAt": "2026-10-04T05:46:37.050Z",
    "updatedAt": "2026-10-04T05:46:37.050Z"
  }
}

HTTP 200. Match item.id and workspaceId to the discovered target. Check quantityOnHand, status and threshold; review decisions do not reverse recorded deltas.

Another supported request

Actual exported Worker response with both local SQLite D1 databases and all committed migrations; synthetic Auth/grants and simulated Notify/Nexus/archive transport. No live delivery, billing or environment deployment proof. Captured scenario: positive sale delta increases stock.

Input · payload.json:

{
  "itemId": "invitem_e5b77ab2-fc66-43fa-a80c-9583d66a0ccb"
}

CLI:

topolo actions validate app_topolo_inventory.items.get --data @payload.json --json
topolo actions plan app_topolo_inventory.items.get --resource-type workspace --resource-id "$INVENTORY_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_inventory.items.get --resource-type workspace --resource-id "$INVENTORY_WORKSPACE_ID" --data @payload.json --json

MCP tool and arguments:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_inventory.items.get",
    "input": {
      "itemId": "invitem_e5b77ab2-fc66-43fa-a80c-9583d66a0ccb"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>"
  }
}

Captured local response · HTTP 200:

{
  "item": {
    "id": "invitem_e5b77ab2-fc66-43fa-a80c-9583d66a0ccb",
    "workspaceId": "ws_inventory_fixture",
    "sku": "WIDGET-BLUE",
    "name": "Blue widget",
    "description": "",
    "unit": "unit",
    "status": "active",
    "lowStockThreshold": 5,
    "quantityOnHand": 2,
    "createdByUserId": "usr_inventory_fixture",
    "createdByEmail": "operator@example.test",
    "createdAt": "2026-10-04T05:46:38.618Z",
    "updatedAt": "2026-10-04T05:46:38.618Z"
  }
}

HTTP 200. Match item.id and workspaceId to the discovered target. Check quantityOnHand, status and threshold; review decisions do not reverse recorded deltas.

Another supported request

Actual exported Worker response with both local SQLite D1 databases and all committed migrations; synthetic Auth/grants and simulated Notify/Nexus/archive transport. No live delivery, billing or environment deployment proof. Captured scenario: rejected movement still affects quantity.

Input · payload.json:

{
  "itemId": "invitem_cf12df06-7056-4441-bef4-95d5c15ef1ed"
}

CLI:

topolo actions validate app_topolo_inventory.items.get --data @payload.json --json
topolo actions plan app_topolo_inventory.items.get --resource-type workspace --resource-id "$INVENTORY_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_inventory.items.get --resource-type workspace --resource-id "$INVENTORY_WORKSPACE_ID" --data @payload.json --json

MCP tool and arguments:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_inventory.items.get",
    "input": {
      "itemId": "invitem_cf12df06-7056-4441-bef4-95d5c15ef1ed"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>"
  }
}

Captured local response · HTTP 200:

{
  "item": {
    "id": "invitem_cf12df06-7056-4441-bef4-95d5c15ef1ed",
    "workspaceId": "ws_inventory_fixture",
    "sku": "WIDGET-BLUE",
    "name": "Blue widget",
    "description": "",
    "unit": "unit",
    "status": "active",
    "lowStockThreshold": 5,
    "quantityOnHand": 10,
    "createdByUserId": "usr_inventory_fixture",
    "createdByEmail": "operator@example.test",
    "createdAt": "2026-10-04T05:46:37.050Z",
    "updatedAt": "2026-10-04T05:46:37.050Z"
  }
}

HTTP 200. Match item.id and workspaceId to the discovered target. Check quantityOnHand, status and threshold; review decisions do not reverse recorded deltas.

Refused request · HTTP 404

Actual exported Worker response with both local SQLite D1 databases and all committed migrations; synthetic Auth/grants and simulated Notify/Nexus/archive transport. No live delivery, billing or environment deployment proof. Captured scenario: missing item.

Input · payload.json:

{
  "itemId": "invitem_missing"
}

CLI:

topolo actions validate app_topolo_inventory.items.get --data @payload.json --json
topolo actions plan app_topolo_inventory.items.get --resource-type workspace --resource-id "$INVENTORY_WORKSPACE_ID" --data @payload.json --json

Captured local response · HTTP 404:

{
  "error": "not_found"
}

HTTP 404. The handler refused this request. Resolve its exact cause before retrying; input validation can reject an invalid fixture before it reaches the handler.

Verify the result

  • Match item.id and workspaceId to the discovered target.
  • Check quantityOnHand, status and threshold; review decisions do not reverse recorded deltas.

Errors and recovery

  • invalid_action_input (HTTP 400): Correct only the exact fields reported by the published schema validator. An invalid input can be refused before its handler.
  • action_permission_required (HTTP 403): Stop when the verified credential lacks the published action permission. Resource identifiers and organization ownership do not grant that permission.
  • organization_required (HTTP 403): Use the specifically authorized organization context; personal scope cannot act on organization-owned Inventory data.
  • workspace_required (HTTP 400): Discover an authorized Inventory workspace and pass its exact separate resource binding; bootstrap does not select a workspace.
  • workspaces_unavailable (HTTP 503): Retain the request id and report unavailable canonical workspace discovery; do not invent a default workspace.
  • not_found (HTTP 404): Discover the resource through the appropriate authorized list or creation response; a foreign or absent identifier is not accessible.

Auth, action-input validation and platform resource resolution can refuse a request before its handler. Retain the exact error, request id and context; requesting another context is not a legitimate way to bypass a refusal.

Recovery boundary

The read does not change local inventory records. No local rollback is needed; do not perform a mutation merely to reverse a read.

  • Update Inventory item: Update an existing item and return its aggregate stock. Descriptive fields omitted from input are preserved, but omitting status sets active and therefore reactivates an archived item.
  • Record Inventory stock movement: Append one nonzero signed quantity delta against an active item and existing location in the same workspace. Movement type labels do not set the sign, pair a transfer or defer stock while review is pending.

Evidence

Captured exported Worker responses use both real local SQLite D1 databases with all six committed migrations, synthetic Auth/workspace grants and simulated Notify/Nexus/archive transport. They prove local handler shapes and scoped behavior, not live authorization, notification delivery, metering acceptance or environment deployment. Large 100-row list/capped-dashboard captures are retained in local evidence; committed tests verify those limits while worked guides use smaller complete responses. Capture digests and test scenarios are retained in the source fixture records.