Skip to content

For developers

Build on top of your fleet.

Two ways in, one set of credentials: a REST API for your own systems, an MCP server for your AI assistant. Permissions you control, down to the individual key.

Open API referenceGet your key

Architecture

How it fits together

The controller talks to us. You talk to the API. Your agent talks through MCP.

  1. 01

    The machine

    Any MDB, EXE, Pulse or RS-232 machine — the protocol the manufacturer already speaks.

  2. 02

    The controller

    Our board sits inside, reads the bus and keeps a link to the platform over cellular.

  3. 03

    The API

    Sales, stock, events and remote commands over HTTPS. Signed webhooks push the moment something happens.

  4. 04

    Your agent

    An MCP client — Claude Code, Claude Desktop, Cursor — reaches the same data with the same permissions.

Quickstart

Three steps to your first response

  1. 01

    Create an API key

    In your SmVend account: Settings → Integration → API. The full key is shown once — store it somewhere safe; afterwards the cabinet only shows its prefix and last four characters. Keys are revocable, can carry an expiry date, and each one is scoped.

    Settings → Integration → API

    API, MCP and the in-app assistant require a Pro subscription plan.

  2. 02

    Call an endpoint

    Every endpoint is a POST with a JSON body, under the v1.2 base URL. Send the key as a Bearer token; add x-user-id when you need the data of one specific user.

    first request
    curl -X POST https://api.smvend.io/v1.2/get-list-of-sales \
  -H "Authorization: Bearer $SMVEND_KEY" \
  -H "content-type: application/json" \
  -d '{"pagination":{"currentPage":1,"perPage":50},
       "dateRange":{"from":1754006400,"to":1754092800}}'
  3. 03

    Verify your webhooks

    Instead of polling, let the platform push. Each delivery is signed with your key’s webhook secret — recompute the HMAC over the timestamp and the raw body, compare in constant time, and reject stale timestamps so a captured delivery cannot be replayed.

    what arrives on the request
    X-SmVend-Signature: t=1756310400,v1=6b2c…  # hex HMAC-SHA256

REST API

Thirty-three endpoints, one key

Base URL api.smvend.io/v1.2 — everything is POST + JSON, so a request looks the same whether you read a report or push a price.

Authentication

An API key sent as a Bearer token. The key is created in the cabinet and carries its own scopes, so an integration only reaches what that particular job needs.

Authorization: Bearer smvd_…

Scopes

read
Reports, statuses, stock, catalog and history endpoints
write
Configuration, matrix, catalog and refill changes, encashments
deposit
Money operations: deposits, free product dispense, remote payments

What the API covers

Controllers

Everything about one machine.

  • List and connection status
  • Runtime state and configuration
  • Product matrix
  • Stock levels

Reports

Paginated history over a date range.

  • Sales with aggregates
  • Events, with a localized dictionary
  • Ingredient consumption

Catalog

Full CRUD over what you sell.

  • Products
  • Resources and ingredients
  • Matrix templates

Operations

Changes and cash handling.

  • Refills, single and batch
  • Encashments
  • Discounts

Money

Requires the deposit scope.

  • Deposits
  • Free product dispense
  • Remote payments

Conventions

  • Date ranges are UNIX timestamps in seconds; the reference states the format per field.
  • Money is in minor units: 100 means 1.00.
  • Ingredient quantities are stored ×100.
  • List endpoints are paginated, with perPage up to 500.
  • Errors return a structured failure with a human-readable message and a traceId you can quote to support.

Reference

The interactive reference carries request and response schemas plus examples for every endpoint. It opens on v1.2; a version selector switches to the legacy v1 spec.

Open the reference

Version 1 is deprecated

The v1 base URL with the x-organization-key header keeps working unchanged until 1 February 2027. Until then every response carries Deprecation and Sunset headers, and existing keys are marked Legacy in the cabinet.

Migration is two steps

  1. 01Create an API key in the cabinet with the same scopes as your legacy key.
  2. 02Point your integration at the v1.2 base URL and send Authorization: Bearer. Paths, request bodies and responses are identical — only authentication differs.

Webhooks

Signed deliveries, not polling

Webhooks configured on an API key are signed with that key’s webhook secret, retrievable in the cabinet. The header carries the timestamp and an HMAC-SHA256 over the timestamp and the raw body.

  • Recompute the HMAC over the exact raw body — parse it after verifying, never before.
  • Compare in constant time, and reject timestamps outside a short window to prevent replay.
  • Deliveries configured on legacy keys keep their previous Ed25519 signature until the same 1 February 2027 sunset.
verify a delivery — Node.js
import crypto from 'node:crypto';

export function verify(header, rawBody, secret) {
  const parts = Object.fromEntries(
    header.split(',').map((p) => p.split('=', 2)),
  );
  const expected = crypto
    .createHmac('sha256', secret)                 // secret: whsec_...
    .update(parts.t + '.' + rawBody)              // raw body, not the parsed object
    .digest('hex');

  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  return fresh && crypto.timingSafeEqual(
    Buffer.from(parts.v1, 'hex'),
    Buffer.from(expected, 'hex'),
  );
}

Model Context Protocol

Your fleet, in your AI assistant

MCP is the open standard AI clients use to reach outside systems. Our server is remote and hosted by us — nothing to install, nothing to run. Point a client at it and the assistant can read your machines and act on them in plain language.

The assistant, the MCP server and the API all run on a Pro subscription.

Connect a client

terminal
claude mcp add --transport http smvend https://mcp.smvend.io/mcp \
  --header "Authorization: Bearer smvd_..."

Every client speaks to the same server — only the config file and its key names differ. The API key goes in an Authorization: Bearer header; legacy x-organization-key keys are still accepted until the v1 sunset, with a migration reminder in every response. Full list of MCP clients and how each one connects

Thirty-three tools, bounded by your key

The tools mirror the API one for one, and your key’s scopes decide what the assistant may actually do. Money operations are annotated, so a well-behaved client asks you to confirm before calling them.

Monitoring

read

What a machine is doing, what it sold, what it has left.

  • list_controllers — every machine you can see, with connection status
  • get_controller_status — online right now, resolved from the last heartbeat
  • get_controller_state — payment systems, inhibit flag, current errors
  • get_controller_matrix — the product grid with prices and resources
  • get_controller_stock — capacity and computed remainder per resource
  • list_sales — sales over a range, with a breakdown by payment type
  • list_events — machine events in plain language
  • list_encashments — cash collections over a range
  • get_consumption — ingredient consumption per resource

Operations

write

Change what the machine does. Matrix updates replace the whole layout.

  • update_controller_config — send only the values you are changing
  • update_controller_matrix — replace grid size, products, prices, resources
  • create_product / update_product / archive_product — the catalogue
  • create_refill / create_refills / list_refills — refill history
  • save_matrix_template — reusable layouts for a fleet
  • create_encashment — register a collection and reset the counters
  • send_discount — push a discount value to a machine

Money

deposit

These move real value. A well-behaved assistant asks you to confirm first.

  • send_deposit — credit the machine balance as if cash went in
  • issue_product — dispense a position free of charge
  • send_remote_payment — register a remote payment

The groups below cover what you reach for first; the full set of thirty-three ships with the server.

Conventions worth knowing

  • Dates in tool arguments are ISO-8601 strings — unlike the REST API, which takes UNIX seconds.
  • Money is in minor units: 100 means 1.00.
  • Ingredient quantities are ×100.
  • List tools page at up to 500 items.
  • update_controller_matrix and save_matrix_template replace rather than merge — send the complete grid.

Security

  • The key is validated by the SmVend API on every single call. The MCP server keeps no copy of it and stores nothing between calls.
  • Issue a separate key for the assistant instead of reusing one from another integration — a read-only key is enough for monitoring and reporting.
  • A key without the deposit scope gets a permission error from the money tools instead of moving money.

claude.ai on the web

Custom connectors on claude.ai sign in with your SmVend account over OAuth — nothing to paste, the connector inherits that account’s permissions. Desktop and editor clients use an API key header instead.

Something missing or wrong?

The reference is updated continuously. If you spot an error, or need an endpoint that is not there yet, write to us — the API team reads it.

support@smvend.io
Ready when you are

Talk to someone who knows vending.

A 20-minute call, honest answers, no pressure. We'll tell you if we're the right fit — and if we're not.

Get demo