Skip to content
Table BuddyTable BuddyRestaurant platform
Sign inGet started
API referenceStock

List materials

Try it

Lists raw materials with their stock on hand and cost, filtered by name or by low stock.

GEThttps://tablebuddy.radioworkflow.com/api/v1/inventory/materials
Read

Paged in id order, archived materials included (is_active false). q matches the name or the code, in any case; below_reorder=true lists what is at or below its low-stock line. A cursor holds only with the same filters. Quantities are milli-units of the material's unit (1.5 kg is 1500), and cost_per_unit is the weighted average for one whole unit. See Money and time.

Authentication

Key
Authorization: Bearer <key>, or the same key in x-api-key. A key acts as the person who made it, cut down to this endpoint’s scope, and never as an owner. How keys work
Scope
inventory:readRead stock and costs
The key's creator needs
View stock (inventory.view)

Request headers

Authorizationrequired
Bearer <key>. x-api-key: <key> works too; Authorization wins when both are sent.
Idempotency-Keyignored
Ignored: a read changes nothing, so there is nothing to repeat. Idempotency

Query parameters

limitinteger1–100optional
Rows per page, 1 to 100.

Default 50.

cursorstringidoptional
next_cursor from the previous page.
qstring1–80 charsoptional
Only materials whose name or code contains this, in any case: 1 to 80 characters, not blank.

Not blank; no NUL character or unpaired surrogate.

below_reorderenumoptional
true for materials at or below their low-stock line, false for the rest.
truefalse

Any other parameter, or one sent twice, is answered 422 invalid_request naming it. A list pages by cursor: see Pagination.

Response

200OK

In id order. A cursor holds only with the same filters.

currencystringISO 4217
The restaurant's currency: every amount in this answer is in its minor units.
minor_digitsinteger0–3
Digits after the point when an amount is shown: 2 for USD (cents), 0 for JPY.
dataarray of object
This page's rows, in the list's order.
data[].idstringid
The material's id.
data[].namestring
Its name.
data[].codestringnullable
Its code, when it has one.
data[].categorystringnullable
Its stockroom category, when set.
data[].unitstring
The unit it is counted in (kg, lb, pcs): every _milli figure is thousandths of it.
data[].stock_milliintegermilli-units
On hand now.
data[].reorder_milliintegermilli-units
The low-stock line: at or below it the material is flagged.
data[].cost_per_unitintegerminor units
Its weighted-average cost of one whole unit.
data[].is_activeboolean
Whether it is in use (not archived).
has_moreboolean
Whether another page follows.
next_cursorstringidnullable
The cursor for the next page: send it as cursor. Null on the last page.

An answer may gain fields within v1: ignore the ones you do not know. Versioning

Response headers

request-idalways
This request’s id. Quote it when asking for help.
Cache-Controlalways
no-store: an answer is never cached.
RateLimit-Limit, RateLimit-Remaining, RateLimit-Resetonce the key is known
The key’s units a minute, what is left of this minute’s, and the seconds until the window starts again. Never on a 401. Rate limits
x-error-codeon an error
The error’s code, the same as error.code in the body.
Retry-Afteron a 429
Seconds to wait before sending the same request again.
WWW-Authenticateon a 401, and a 403 insufficient_scope
The Bearer challenge, naming what was wrong with the key or the scope it lacks.

Errors

403insufficient_scope
The key does not carry the endpoint's scope.

Fix: Scopes are fixed when a key is made: make a new key with the scope.

403issuer_access_ended
The key's creator has left the restaurant, was suspended, or was removed and invited back.

Fix: Make a new key from an active account.

403issuer_permission_changed
The key's creator no longer holds any permission that could put this scope on a key.

Fix: Ask an owner to restore the permission, or make a new key from an account that holds it.

403permission_required
The key's permissions for this endpoint (its creator's, cut down to the endpoint's scope) do not include what this endpoint, or this argument, needs. The message names it.

Fix: Use a key with the named scope, from a creator who holds the named permission.

422invalid_request
A filter out of range: q blank or over 80 characters, or below_reorder other than true or false.

Fix: Fix the named fields. Nothing was done, and an Idempotency-Key is not used up.

422invalid_cursor
The cursor is not a material in this list with these filters.

Fix: Start without cursor, keeping the same filters.

Possible on every endpoint
401missing_api_keyNo Authorization: Bearer header and no x-api-key header.
401invalid_api_keyThe key is unknown, revoked or expired (answered alike).
429rate_limitedOver the key's 60 units a minute, or over 30 unknown keys a minute from one network (an address; an IPv6 caller's /64).
500internal_errorSomething failed on our side. Nothing kept the Idempotency-Key.

Every code, and when to retry

Request
curl -X GET "$TABLEBUDDY_URL/api/v1/inventory/materials?below_reorder=true" \
  -H "Authorization: Bearer $TABLEBUDDY_API_KEY"
Response200
{
  "currency": "USD",
  "minor_digits": 2,
  "data": [
    {
      "id": "cmg5x4d2e0001tb2jh7p3k5sa",
      "name": "Atlantic salmon fillet",
      "code": "SAL-1",
      "category": "Seafood",
      "unit": "lb",
      "stock_milli": 18500,
      "reorder_milli": 10000,
      "cost_per_unit": 1150,
      "is_active": true
    }
  ],
  "has_more": false,
  "next_cursor": null
}