Connect AI assistants and apps to your VTM machines

Connect an AI assistant to ask questions about your machines, or use an API key to bring your data into a spreadsheet, dashboard, or other software.

Both options give you read-only access to machines on your VTM account. They can look up machine status, stock, and sales. To change prices, stock, or settings, use the VTM Vending Web Portal.

Before you begin

Sign in to the VTM Vending Web Portal. At least one machine on your account must have an active subscription to use API & AI.

Note: API & AI is in beta. Some screens and labels may change.

Open API & AI

In the Web Portal sidebar, scroll to Administration.
Click API & AI.

The Overview tab shows your access status, calls this month, and active keys. Choose the option that fits what you want to do:

Connect an AI assistant to ask questions in plain language. No code is needed.
Build with the API to use your data in your own software or spreadsheets.

Connect an AI assistant

You can connect Claude, ChatGPT, Cursor, and other assistants that support a remote MCP connection with OAuth sign-in. MCP is the connection that lets your assistant look up your VTM data.

Copy your connection link

Open the AI assistants tab.
Under Your MCP, click Copy next to the MCP link.

https://api.vtmvending.com/mcp

Under How to connect, choose your assistant’s tab. Follow the steps for your assistant below, then complete the VTM sign-in when prompted.

Claude

In Claude, open Settings → Connectors.
Click Add custom connector.
Enter VTM Vending as the name and paste the MCP link.
Click Add, then Connect. Sign in with your VTM email and password.
Start a chat and ask about your machines. Review any tool permission request before continuing.

ChatGPT

These steps match the Plugins interface shown below. Available options may vary by account or workspace.

In ChatGPT, open Plugins from the sidebar.
Click Add (+), then choose Add custom MCP server.
Enter VTM Vending in Name.
Choose Server URL and paste the MCP link.
Set Authentication to OAuth.
Read the notice and select I understand and want to continue.
Click Create as a plugin and follow the prompts to connect your VTM account.

VTM Vending custom MCP server form in ChatGPT

After connecting, start a chat with VTM Vending available and ask a question about your machines.

Claude Code

Run this command in your terminal:

claude mcp add --transport http vtm https://api.vtmvending.com/mcp

In Claude Code, run /mcp, choose vtm, and follow the sign-in prompts.

Cursor

In the Web Portal, select the Cursor tab under How to connect.
Click + Add to Cursor.
In Cursor’s MCP settings, click Connect next to VTM and sign in.

VS Code

In the Web Portal, select the VS Code tab under How to connect.
Click + Add to VS Code.
Start the server from the MCP view in VS Code and follow the sign-in prompts.

Other assistants

Add https://api.vtmvending.com/mcp as a remote MCP server and use OAuth for sign-in. Your assistant’s setup format may differ. For clients that use an mcpServers configuration, the connection may look like this:

{
  "mcpServers": {
    "vtm": {
      "url": "https://api.vtmvending.com/mcp"
    }
  }
}

When prompted, sign in with your VTM email and password.

Ask about your machines

Start with a question such as “Which of my machines are offline right now?” Include a machine name or date range when you want a more specific answer.

Your assistant can use six read-only tools. To see them in the Web Portal, expand MCP tools on the AI assistants tab.

List machines: See names, locations, online status, last seen times, and subscription expiry dates.
Get machine: Look up details for one machine.
Get inventory: Check products, stock levels, capacity, low-stock thresholds, prices, and aisle faults.
List orders: Review individual sales, including the product, aisle, quantity, amount paid, payment status, and time.
Get order: Look up an order by its order number.
Sales summary: Compare completed sales and revenue across machines for a date range.

Try asking:

“When was the Main Street machine last online?”
“Which aisles are below their low-stock threshold?”
“Show me yesterday’s sales on my airport machine.”
“Which machine made the most money last month?”

Simulated ChatGPT conversation using example machine data

The chat example uses simulated machine data.

Disconnect an assistant

Remove VTM Vending from the assistant’s connector or plugin settings.
In the Web Portal, open API & AI → API keys.
Find the assistant’s key, marked AI assistant, and click Revoke. Confirm when prompted.

An assistant can create a separate key each time it signs in, so you may see more than one. Revoke each relevant key to remove its VTM access.

Build with the API

Use an API key to read your machine data from a spreadsheet, dashboard, or application. Each tool should have its own key so you can remove one connection without affecting the others.

Create an API key

Open the API keys tab.
Click + Create API key.

API keys tab with Create API key highlighted

Name your key

Enter a descriptive name, such as Inventory spreadsheet. If you leave the name blank, VTM assigns a numbered name, such as API key 1.
Click Create key.

Create API key window with Inventory spreadsheet entered

Save your key

Click Copy and save the key securely. The full key is shown only once.
When you have saved it, click I’ve saved my key.

Save your API key window with the unique key characters hidden

Keep your key private. Anyone with it can read data on your account. Don’t include it in emails, shared screenshots, public code, or websites that expose it to visitors. If you lose a key, revoke it and create a replacement.

The API keys tab shows when each key was created, when it was last used, its calls this month, and its status. Assistant connections are marked AI assistant; other keys are marked API key.

Make your first request

Send your key in the X-API-Key header. All requests go to https://api.vtmvending.com.

This example lists offline machines. Replace YOUR_API_KEY with your key before running it:

curl "https://api.vtmvending.com/api/v1/machines?status=offline" \
  -H "X-API-Key: YOUR_API_KEY"

The response places your results inside data. Lists include records, the overall total, and the current page and size.

{
  "code": 200,
  "message": "success",
  "data": {
    "records": [
      {
        "machineNo": "YOUR_MACHINE_NUMBER",
        "name": "Main Street",
        "status": "offline",
        "lastSeen": "2026-10-26T08:14:02.000+00:00"
      }
    ],
    "total": 1,
    "page": 1,
    "size": 20
  }
}

Open the Docs tab for JavaScript and Python examples. For all fields and request options, click API reference at the top right of the API & AI page.

Choose an endpoint

Use the 15-digit machine number shown on the Machines page wherever an endpoint requires machineNo.

Machines

GET /api/v1/machines — List machines. Optional filters: status (online or offline), page, and size (up to 100).
GET /api/v1/machines/{machineNo} — Get one machine’s details.

Inventory

GET /api/v1/inventory — Get aisle stock across machines. Optionally filter with machineNos, repeated or separated by commas.
GET /api/v1/inventory/machines/{machineNo} — Get aisle stock for one machine.

Orders

GET /api/v1/orders — List orders, newest first. Filters: machineNo, startTime, endTime, page, and size (up to 100).
GET /api/v1/orders/{orderNumber} — Get an order and its items.
GET /api/v1/orders/summary — Get sales counts and revenue per machine. Filters: startTime and endTime.

Use yyyy-MM-dd HH:mm:ss for date filters. For example: 2026-10-01 00:00:00.

Understand pages and request limits

Pages: Lists start at page=1. Set size to request up to 100 results per page. Use total to check whether more results are available.

Hourly limit: Your account gets 1,000 requests per hour for each machine with an active subscription. Three subscribed machines provide 3,000 requests per hour. All keys share this allowance; creating more keys does not increase it.

Short-term limit: Your account can make up to 20 requests per second.

Check the X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset response headers to monitor your allowance.

If a request fails

401: Check that the X-API-Key header is included and the key is correct and active.
403: Check that at least one machine has an active subscription and the key has access to the requested endpoint.
404: Check the machine or order number. It must belong to your account.
429: You have reached a request limit. Wait the number of seconds in the Retry-After header, then try again.

Replace or revoke a key

To replace a key without interrupting your connection:

Create a new key on the API keys tab.
Update your software to use the new key and check that it works.
Click Revoke next to the old key, then click Revoke again to confirm.

Revoking a key takes effect immediately and cannot be undone. Anything still using that key will stop working. To review removed keys, select Show revoked keys below the key list.

Check your usage

Open the Usage tab and choose 7 days, 30 days, or 90 days to review requests made by your API keys and AI assistants.

Summary totals: See Today, This month, Last 30 days, and Machines asked about.
Calls per day: See how activity changes over time.
By key: See which keys and assistants are making requests. Revoked keys are crossed out.
By machine: See which machines are being looked up. All machines counts requests that did not name a specific machine, such as listing all your machines.

Usage tab with key names and machine numbers blurred

If you see activity from a key you don’t recognize, review it on the API keys tab and revoke it if it should no longer have access.

Get help

If an assistant won’t connect or API requests keep failing, contact VTM Support. Include the assistant or tool you’re using, the key’s name, any error or status code, and the time the problem occurred. Never send the API key itself.