Getting Started

Base URL

All endpoints are served under the versioned /api/v1 prefix:

Base URL

https://tina-api.venhub.com/api/v1

For example, hub_inventory is reached at https://tina-api.venhub.com/api/v1/owners/hub_inventory/.

Authentication

All endpoints require authentication via one of the following methods:

Method	Header	Description
API Key	`X-API-Key: vh_...`	Third-party API key authentication
Firebase	`Authorization: Bearer <token>`	Firebase user authentication

ℹ️

Keys are generated in TINA, the VenHub dashboard — not via an API call. Managing hubs for your own customers? Add them as an operator in TINA and they can generate their own key directly. See the Authentication guide for details on generating keys and permission scopes.

Permission Scopes

API keys are issued with one or more scopes. Each endpoint requires a specific scope. Requesting an endpoint without the required scope returns a 403 scope_missing error.

Scope	Access	Endpoints
`inventory:read`	Read inventory data	GET /hub_inventory, GET /hubs/product
`inventory:write`	Modify inventory data	update_quantity, update_price, update_purchase_price, update_upc
`orders:read`	View orders	GET /all_orders_paginated
`orders:write`	Process refunds	POST /refund, POST /items/{id}/refund
`analytics:read`	View sales analytics	All GET /analytics endpoints
`hubs:read`	View hub info & status	GET /hubs, /hub_ids, /get_hub_info, /hub_layout, /get_hub_health, /get_door_status, /fridge_door_cabinet_map
`hubs:write`	Control hub access	POST /request_door_open
`controls:read`	Read hardware status	GET /controls/get_bin_status
`controls:write`	Send hardware commands	All POST /controls endpoints
`maintenance:read`	View maintenance reports	GET /maintenance/reports, GET /maintenance/reports/{id}
`maintenance:write`	Create maintenance reports	POST /maintenance/reports
`promotions:read`	View banners & deals	GET /owner/banners, GET /deals/*
`promotions:write`	Manage banners & deals	POST /owner/banners, POST/PUT/DELETE /deals/*

Your First Request

Once you have an API key with inventory:read scope, fetch your hub's inventory:

cURL

curl -X GET \
  "https://tina-api.venhub.com/api/v1/owners/hub_inventory/?hub_id=123" \
  --header "X-API-Key: vh_your_key_here" \
  --header "Content-Type: application/json"

A successful response looks like:

JSON Response — 200 OK

[
  {
    "id": 1,
    "name": "Organic Apple",
    "upc": "012345678901",
    "quantity": 25,
    "original_price": 299,
    "discounted_price": 299,
    "cabinet": 1,
    "shelf": 2,
    "row": 3
  }
]

API Conventions

Convention	Details
Money	All prices and amounts are integers in cents. `299` = $2.99
Timestamps	All timestamps are ISO 8601 in UTC, e.g. `2026-02-05T14:30:00Z`
Pagination	Uses cursor-based pagination. Pass the `next_cursor` value as `cursor` in subsequent requests.
Content-Type	All request bodies must be `application/json`
API Version	Currently v1, versioned explicitly via the `/api/v1` URL prefix.

Payments

VenHub has no payments endpoint. VenHub partners with Stripe, so most integrators build on that — but whichever processor you use, you build the integration and verify the charge yourself. Once you've verified payment, you let VenHub know by calling POST /controls/open_bin — VenHub treats that call itself as your confirmation and continues the transaction from there. VenHub never touches card data or checks payment status.

Next Steps

🔑

Authentication

Hubs API

Inventory API

Orders API

Analytics API

Maintenance API

Controls API

Promotions API

Error Reference

Base URL

Authentication

Permission Scopes

Your First Request

API Conventions

Payments

Next Steps

Set up auth

Hubs endpoints

Inventory endpoints

Orders endpoints

Analytics endpoints

Controls endpoints