Home › Docs › Controls API

Controls API

Endpoints for direct hardware control of vending bins and refrigerated cabinets. All control endpoints require the controls:write or controls:read scope.

ℹ️
The contents of response_data aren't documented by the API and may be empty or vary by action, so don't rely on a fixed shape for it beyond what's shown per endpoint below.

Bin Controls

POST /controls/open_bin

Open a specific vending bin door.

Version1
URLhttps://tina-api.venhub.com/api/v1/owners/controls/open_bin
AuthAPI Key or Firebase
Required Scopecontrols:write

Example Request

cURL
curl -X POST \
  "https://tina-api.venhub.com/api/v1/owners/controls/open_bin?bin=1&hub=123" \
  --header "X-API-Key: vh_abc123..."

Parameters

ParameterTypeLocationRequiredDescription
binIntegerQueryRequiredBin number (1–4)
hubIntegerQueryRequiredHub ID

Response

JSON — 200 OK
{
  "status": "ok",
  "result": {
    "success": true,
    "status_code": 200,
    "response_data": null
  }
}

Errors

Error CodeDescription
hub_access_deniedAPI key does not have access to the specified hub
bin_not_foundThe specified bin number does not exist on this hub
hardware_errorFailed to communicate with bin hardware
POST /controls/close_bin

Close a specific vending bin door.

Version1
URLhttps://tina-api.venhub.com/api/v1/owners/controls/close_bin
AuthAPI Key or Firebase
Required Scopecontrols:write

Example Request

cURL
curl -X POST \
  "https://tina-api.venhub.com/api/v1/owners/controls/close_bin?bin=1&hub=123" \
  --header "X-API-Key: vh_abc123..."

Parameters

ParameterTypeLocationRequiredDescription
binIntegerQueryRequiredBin number (1–4)
hubIntegerQueryRequiredHub ID

Response

JSON — 200 OK
{
  "status": "ok",
  "result": {
    "success": true,
    "status_code": 200,
    "response_data": null
  }
}
POST /controls/enable_bin

Enable a bin to accept customer orders.

Version1
URLhttps://tina-api.venhub.com/api/v1/owners/controls/enable_bin
AuthAPI Key or Firebase
Required Scopecontrols:write

Example Request

cURL
curl -X POST \
  "https://tina-api.venhub.com/api/v1/owners/controls/enable_bin?bin=1&hub=123" \
  --header "X-API-Key: vh_abc123..."

Parameters

ParameterTypeLocationRequiredDescription
binIntegerQueryRequiredBin number (1–4)
hubIntegerQueryRequiredHub ID

Response

JSON — 200 OK
{
  "status": "ok",
  "result": {
    "success": true,
    "status_code": 200,
    "response_data": null
  }
}
POST /controls/disable_bin

Disable a bin from accepting orders (maintenance mode).

Version1
URLhttps://tina-api.venhub.com/api/v1/owners/controls/disable_bin
AuthAPI Key or Firebase
Required Scopecontrols:write

Example Request

cURL
curl -X POST \
  "https://tina-api.venhub.com/api/v1/owners/controls/disable_bin?bin=1&hub=123" \
  --header "X-API-Key: vh_abc123..."

Parameters

ParameterTypeLocationRequiredDescription
binIntegerQueryRequiredBin number (1–4)
hubIntegerQueryRequiredHub ID

Response

JSON — 200 OK
{
  "status": "ok",
  "result": {
    "success": true,
    "status_code": 200,
    "response_data": null
  }
}
GET /controls/get_bin_status

Get current operational status of a bin.

Version1
URLhttps://tina-api.venhub.com/api/v1/owners/controls/get_bin_status
AuthAPI Key or Firebase
Required Scopecontrols:read

Example Request

cURL
curl -X GET \
  "https://tina-api.venhub.com/api/v1/owners/controls/get_bin_status?bin=1&hub=123" \
  --header "X-API-Key: vh_abc123..."

Parameters

ParameterTypeLocationRequiredDescription
binIntegerQueryRequiredBin number (1–4)
hubIntegerQueryRequiredHub ID

Response

JSON — 200 OK
{
  "status": "ok",
  "result": {
    "success": true,
    "status_code": 200,
    "response_data": null
  }
}
POST /controls/toggle_bin

Toggle bin enabled/disabled state.

Version1
URLhttps://tina-api.venhub.com/api/v1/owners/controls/toggle_bin
AuthAPI Key or Firebase
Required Scopecontrols:write

Example Request

cURL
curl -X POST \
  "https://tina-api.venhub.com/api/v1/owners/controls/toggle_bin?bin=1&hub=123" \
  --header "X-API-Key: vh_abc123..."

Parameters

ParameterTypeLocationRequiredDescription
binIntegerQueryRequiredBin number (1–4)
hubIntegerQueryRequiredHub ID

Response

JSON — 200 OK
{
  "status": "ok",
  "result": {
    "success": true,
    "status_code": 200,
    "response_data": null
  }
}
POST /controls/raise_bin

Raise the lift panel for product retrieval.

Version1
URLhttps://tina-api.venhub.com/api/v1/owners/controls/raise_bin
AuthAPI Key or Firebase
Required Scopecontrols:write

Example Request

cURL
curl -X POST \
  "https://tina-api.venhub.com/api/v1/owners/controls/raise_bin?bin=1&hub=123" \
  --header "X-API-Key: vh_abc123..."

Parameters

ParameterTypeLocationRequiredDescription
binIntegerQueryRequiredBin number (1–4)
hubIntegerQueryRequiredHub ID

Response

JSON — 200 OK
{
  "status": "ok",
  "result": {
    "success": true,
    "status_code": 200,
    "response_data": null
  }
}
POST /controls/lower_bin

Lower the lift panel after restocking.

Version1
URLhttps://tina-api.venhub.com/api/v1/owners/controls/lower_bin
AuthAPI Key or Firebase
Required Scopecontrols:write

Example Request

cURL
curl -X POST \
  "https://tina-api.venhub.com/api/v1/owners/controls/lower_bin?bin=1&hub=123" \
  --header "X-API-Key: vh_abc123..."

Parameters

ParameterTypeLocationRequiredDescription
binIntegerQueryRequiredBin number (1–4)
hubIntegerQueryRequiredHub ID

Response

JSON — 200 OK
{
  "status": "ok",
  "result": {
    "success": true,
    "status_code": 200,
    "response_data": null
  }
}
POST /controls/cycle_bin

Cycle a bin door open/close multiple times (for testing).

Version1
URLhttps://tina-api.venhub.com/api/v1/owners/controls/cycle_bin
AuthAPI Key or Firebase
Required Scopecontrols:write

Example Request

cURL
curl -X POST \
  "https://tina-api.venhub.com/api/v1/owners/controls/cycle_bin?bin=1&hub=123&num_cycles=3" \
  --header "X-API-Key: vh_abc123..."

Parameters

ParameterTypeLocationRequiredDescription
binIntegerQueryRequiredBin number (1–4)
hubIntegerQueryRequiredHub ID
num_cyclesIntegerQueryRequiredNumber of times to cycle the door

Response

JSON — 200 OK
{
  "status": "ok",
  "result": {
    "success": true,
    "status_code": 200,
    "response_data": null
  }
}
POST /controls/reconnect_bin

Reconnect communication to a bin after connection loss.

Version1
URLhttps://tina-api.venhub.com/api/v1/owners/controls/reconnect_bin
AuthAPI Key or Firebase
Required Scopecontrols:write

Example Request

cURL
curl -X POST \
  "https://tina-api.venhub.com/api/v1/owners/controls/reconnect_bin?bin=1&hub=123" \
  --header "X-API-Key: vh_abc123..."

Parameters

ParameterTypeLocationRequiredDescription
binIntegerQueryRequiredBin number (1–4)
hubIntegerQueryRequiredHub ID

Response

JSON — 200 OK
{
  "status": "ok",
  "result": {
    "success": true,
    "status_code": 200,
    "response_data": null
  }
}
POST /controls/enable_bin_ssh

Enable a bin over the SSH management channel, bypassing the primary control path.

Version1
URLhttps://tina-api.venhub.com/api/v1/owners/controls/enable_bin_ssh
AuthAPI Key or Firebase
Required Scopecontrols:write

Example Request

cURL
curl -X POST \
  "https://tina-api.venhub.com/api/v1/owners/controls/enable_bin_ssh?bin=1&hub=123" \
  --header "X-API-Key: vh_abc123..."

Parameters

ParameterTypeLocationRequiredDescription
binIntegerQueryRequiredBin number
hubIntegerQueryRequiredHub ID

Response

JSON — 200 OK (success)
{
  "status": "ok",
  "result": {
    "success": true,
    "hub_id": 123,
    "bin_number": 1,
    "enabled_bin": 1,
    "disabled_bins": [2, 3, 4],
    "stop_result": null,
    "start_result": null
  }
}
JSON — 200 OK (error)
{
  "status": "error",
  "result": {
    "success": false,
    "error": "Bin 1 not found on hub 123",
    "error_type": "validation_error",
    "hub_id": 123,
    "bin_number": 1
  }
}
POST /controls/disable_bin_ssh

Disable a bin over the SSH management channel, bypassing the primary control path.

Version1
URLhttps://tina-api.venhub.com/api/v1/owners/controls/disable_bin_ssh
AuthAPI Key or Firebase
Required Scopecontrols:write

Example Request

cURL
curl -X POST \
  "https://tina-api.venhub.com/api/v1/owners/controls/disable_bin_ssh?bin=1&hub=123" \
  --header "X-API-Key: vh_abc123..."

Parameters

ParameterTypeLocationRequiredDescription
binIntegerQueryRequiredBin number
hubIntegerQueryRequiredHub ID

Response

JSON — 200 OK (success)
{
  "status": "ok",
  "result": {
    "success": true,
    "hub_id": 123,
    "bin_number": 1,
    "enabled_bin": 1,
    "disabled_bins": [1],
    "stop_result": null,
    "start_result": null
  }
}
JSON — 200 OK (error)
{
  "status": "error",
  "result": {
    "success": false,
    "error": "Bin 1 not found on hub 123",
    "error_type": "validation_error",
    "hub_id": 123,
    "bin_number": 1
  }
}

Fridge Controls

POST /controls/open_fridge_left

Open the left door of a refrigerated cabinet.

Version1
URLhttps://tina-api.venhub.com/api/v1/owners/controls/open_fridge_left
AuthAPI Key or Firebase
Required Scopecontrols:write

Example Request

cURL
curl -X POST \
  "https://tina-api.venhub.com/api/v1/owners/controls/open_fridge_left?fridge=1&hub=123" \
  --header "X-API-Key: vh_abc123..."

Parameters

ParameterTypeLocationRequiredDescription
fridgeIntegerQueryRequiredFridge number
hubIntegerQueryRequiredHub ID

Response

JSON — 200 OK
{
  "status": "ok",
  "result": {
    "success": true,
    "status_code": 200,
    "response_data": null
  }
}
POST /controls/open_fridge_right

Open the right door of a refrigerated cabinet.

Version1
URLhttps://tina-api.venhub.com/api/v1/owners/controls/open_fridge_right
AuthAPI Key or Firebase
Required Scopecontrols:write

Example Request

cURL
curl -X POST \
  "https://tina-api.venhub.com/api/v1/owners/controls/open_fridge_right?fridge=1&hub=123" \
  --header "X-API-Key: vh_abc123..."

Parameters

ParameterTypeLocationRequiredDescription
fridgeIntegerQueryRequiredFridge number
hubIntegerQueryRequiredHub ID

Response

JSON — 200 OK
{
  "status": "ok",
  "result": {
    "success": true,
    "status_code": 200,
    "response_data": null
  }
}
POST /controls/open_fridge_middle

Open the middle door of a refrigerated cabinet.

Version1
URLhttps://tina-api.venhub.com/api/v1/owners/controls/open_fridge_middle
AuthAPI Key or Firebase
Required Scopecontrols:write

Example Request

cURL
curl -X POST \
  "https://tina-api.venhub.com/api/v1/owners/controls/open_fridge_middle?fridge=1&hub=123" \
  --header "X-API-Key: vh_abc123..."

Parameters

ParameterTypeLocationRequiredDescription
fridgeIntegerQueryRequiredFridge number
hubIntegerQueryRequiredHub ID

Response

JSON — 200 OK
{
  "status": "ok",
  "result": {
    "success": true,
    "status_code": 200,
    "response_data": null
  }
}
POST /controls/close_fridge

Close a refrigerated cabinet door.

Version1
URLhttps://tina-api.venhub.com/api/v1/owners/controls/close_fridge
AuthAPI Key or Firebase
Required Scopecontrols:write

Example Request

cURL
curl -X POST \
  "https://tina-api.venhub.com/api/v1/owners/controls/close_fridge?fridge=1&hub=123" \
  --header "X-API-Key: vh_abc123..."

Parameters

ParameterTypeLocationRequiredDescription
fridgeIntegerQueryRequiredFridge number
hubIntegerQueryRequiredHub ID

Response

JSON — 200 OK
{
  "status": "ok",
  "result": {
    "success": true,
    "status_code": 200,
    "response_data": null
  }
}
POST /controls/enable_fridge

Enable a refrigerated cabinet for operation.

Version1
URLhttps://tina-api.venhub.com/api/v1/owners/controls/enable_fridge
AuthAPI Key or Firebase
Required Scopecontrols:write

Example Request

cURL
curl -X POST \
  "https://tina-api.venhub.com/api/v1/owners/controls/enable_fridge?fridge=1&hub=123" \
  --header "X-API-Key: vh_abc123..."

Parameters

ParameterTypeLocationRequiredDescription
fridgeIntegerQueryRequiredFridge number
hubIntegerQueryRequiredHub ID

Response

JSON — 200 OK
{
  "status": "ok",
  "result": {
    "success": true,
    "status_code": 200,
    "response_data": null
  }
}
POST /controls/disable_fridge

Disable a refrigerated cabinet (maintenance mode).

Version1
URLhttps://tina-api.venhub.com/api/v1/owners/controls/disable_fridge
AuthAPI Key or Firebase
Required Scopecontrols:write

Example Request

cURL
curl -X POST \
  "https://tina-api.venhub.com/api/v1/owners/controls/disable_fridge?fridge=1&hub=123" \
  --header "X-API-Key: vh_abc123..."

Parameters

ParameterTypeLocationRequiredDescription
fridgeIntegerQueryRequiredFridge number
hubIntegerQueryRequiredHub ID

Response

JSON — 200 OK
{
  "status": "ok",
  "result": {
    "success": true,
    "status_code": 200,
    "response_data": null
  }
}
POST /controls/reconnect_fridge

Reconnect communication to a fridge after connection loss.

Version1
URLhttps://tina-api.venhub.com/api/v1/owners/controls/reconnect_fridge
AuthAPI Key or Firebase
Required Scopecontrols:write

Example Request

cURL
curl -X POST \
  "https://tina-api.venhub.com/api/v1/owners/controls/reconnect_fridge?fridge=1&hub=123" \
  --header "X-API-Key: vh_abc123..."

Parameters

ParameterTypeLocationRequiredDescription
fridgeIntegerQueryRequiredFridge number
hubIntegerQueryRequiredHub ID

Response

JSON — 200 OK
{
  "status": "ok",
  "result": {
    "success": true,
    "status_code": 200,
    "response_data": null
  }
}

Order Flow Controls

POST /controls/stop_orders

Pause new customer orders hub-wide, independent of any single bin or fridge.

Version1
URLhttps://tina-api.venhub.com/api/v1/owners/controls/stop_orders
AuthAPI Key or Firebase
Required Scopecontrols:write

Example Request

cURL
curl -X POST \
  "https://tina-api.venhub.com/api/v1/owners/controls/stop_orders?hub=123" \
  --header "X-API-Key: vh_abc123..."

Parameters

ParameterTypeLocationRequiredDescription
hubIntegerQueryRequiredHub ID — the only parameter this endpoint takes

Response

JSON — 200 OK
{
  "status": "ok",
  "result": {
    "success": true,
    "status_code": 200,
    "response_data": null
  }
}
POST /controls/resume_orders

Resume customer orders hub-wide after a stop_orders call.

Version1
URLhttps://tina-api.venhub.com/api/v1/owners/controls/resume_orders
AuthAPI Key or Firebase
Required Scopecontrols:write

Example Request

cURL
curl -X POST \
  "https://tina-api.venhub.com/api/v1/owners/controls/resume_orders?hub=123" \
  --header "X-API-Key: vh_abc123..."

Parameters

ParameterTypeLocationRequiredDescription
hubIntegerQueryRequiredHub ID — the only parameter this endpoint takes

Response

JSON — 200 OK
{
  "status": "ok",
  "result": {
    "success": true,
    "status_code": 200,
    "response_data": null
  }
}