Docs

Changelog

What changed in the Servicebay API, MCP server and developer docs

Changes to the REST API, the MCP server and these docs, newest first. Dates are when the change reached production.

November 2026 — stock, customer records, payments, and MCP without ids

This update brings the API and the MCP server up to date with the Servicebay app releases 2.2.2 to 2.4.6.

Action needed

Six changes can affect an existing integration.

ChangeWho it affectsWhat to do
PUT /inventory/{itemId} no longer changes stockCount. A different value returns 409 STOCK_COUNT_SERVER_OWNEDIntegrations that set stock by updating the itemUse POST /inventory/{itemId}/stock-adjustments (reason: "stockCount" to set a counted figure)
DELETE of a status / assignee / station entry in a job's log returns 400Integrations that tidy up job logsNothing to replace it: those entries are a record. Notes and messages delete as before
PUT /customers/{id} that changes an address part without sending latitude / longitude now clears the stored coordinatesIntegrations that update addresses and read the coordinates backSend latitude and longitude with the new address to keep or set them
MCP tools no longer return or accept database idsAnyone with prompts, instructions or automations built on the MCP tools' old inputs (id, customerId, sb:{entity}:{id})Refer to records by number or name; see MCP → Naming a record. Reconnect is not needed
A message link's url, imageUrl and faviconUrl, and the organisation's website, must be http or https. Any other scheme returns 400Integrations that post links with a custom scheme (myapp://…, tel:, mailto:)Send web addresses only. Put anything else in the message text
Dynamic client registration refuses a client_name with control or bidirectional formatting characters (400 invalid_client_metadata)OAuth clients that register themselves with such a nameRegister with a plain name

Everything else below adds fields, filters, endpoints or tools, or fixes a bug; none of it needs a change on your side.

Stock

Servicebay now keeps stock levels that move with jobs and invoices, across stock locations. See the new Stock page.

  • Job inventory lines and invoice / quote inventoryItems accept and return catalogueItemId. A line that names its inventory item moves that item's stock; tracksStock is filled in from the item when you leave it out.
  • New: POST /inventory/{itemId}/stock-adjustments, POST /stock-transfers, POST /stock-returns, and GET /stock-requests/{requestId}. They use the same stock code as the app, so the history, per-location counts and low-stock alerts match. Idempotent on requestId.
  • New: GET /stock-movements (the stock history) and GET /stock-locations.
  • Inventory items: reorderLevel (writable), stockByLocation and lowStockAlertedAt (read-only).
  • stockLocationId (Stock From) on jobs and on invoices not made from a job.

Customer records

  • New: GET /customers/{customerId}/records and GET /customers/{customerId}/records/{recordId}. See Customer records. Secret values are never returned.
  • New scope customer-records:read. It is not part of read, write or full, so no existing API key or connected app gained it. Grant it by name.

Payments

  • Payments return recordedAt, customerName, invoiceIndex, stripeChannel (online / tapToPay / cardReader) and accountingSource (xero / quickbooks).
  • GET /payments accepts from and to on paymentDate.

Jobs and the job log

  • Messages return attachments, editedAt and changeId; link previews accept and return siteName and faviconUrl. Updating a message stamps editedAt.
  • Status, assignee and station entries now say what the value was: messageParams.from, fromId and toId (toId: null means none).

Invoices, quotes and customers

  • GET /invoices and GET /quotes accept number to find a document by the number people know it by. number is a lookup of its own; combined with another filter it is a 400.
  • Fixed: an invoice or quote created in the app could not be written back through the API when its lines carried xeroItemCode, quickBooksItemId or catalogueItemId (400). Those fields are now accepted and kept.
  • Deleting an invoice deletes its reminders in the same step.
  • Fixed: a partial PUT could reset fields you did not send to their defaults — a job's status to Open, a job line's quantity to 1, a calendar event's allDay to false, a recurring schedule's end condition to "never". An update now changes only the fields in the request.
  • A calendar event can be unassigned: send assignedToId and assignedTo as empty strings.
  • Updating a customer's address without sending coordinates now clears the stored latitude / longitude, which described the old address.

MCP

  • MCP tools no longer return database ids and no longer take them. Records are named by number or name; every record carries an opaque ref for follow-up calls. This covers results, error messages (an id in an API error is replaced by the record's name, or hidden), the choices offered when a name matches several records, and the page a citation link opens. When several records match a name, the tool answers needsChoice instead of guessing. See MCP → Tools.
  • An update never drops what it did not change: invoice and quote lines carry a ref that keeps their catalogue item, tax rate and category through a read and a save, so editing an invoice through MCP does not move its stock.
  • A job's parts and service lines are record types of their own (job-parts, job-services).
  • A phone number or email that two customers share is never resolved to one of them, however each is written.
  • search by text matches every word across up to 500 records of each type, instead of filtering one page. Lists no longer take a search filter.
  • whoami names the organisation and no longer returns its id.
  • Fixed on 18 November: list_resources answered "Output validation error" instead of the choices when a name matched several records, and errors from list_resources, search and fetch showed as "Structured content does not match the tool's output schema" in clients that check it. search no longer answers "nothing found" when the API refused or failed the reads it needed (an expired credential, an outage): it returns the error, or what it found with a note. A change that got no readable answer says whether it may have been made (outcome_unknown, response_lost) instead of failing with a connection error; a stock tool then returns the request to check. Every API refusal now reads as JSON in the result's text, the 401 and missing-permission 403 included. A conversation opened before the update keeps the old tool list; start a new one, or disconnect and reconnect, to pick up the new tools.
  • New tools: adjust_stock, transfer_stock, return_stock, get_stock_request. The three that change stock take an optional idempotencyKey, so a retried call moves stock once.
  • Each record type is its own entity (stock-movements, stock-locations, inventory-categories, asset-categories, form-templates, form-rules, form-submissions, recurring-presets, customer-records); the kind and collection arguments are gone.
  • Citation links are https://developer.servicebay.io/r/{ref}. Older /r/{org}/{entity}/{id} links keep working.
  • The Google profile (/mcp/google/v1) has the same tools and schemas as before. One answer changed on 18 November: when the API cannot be reached it now says "Servicebay could not complete the request (HTTP 503). Try again shortly." instead of the raw connection error.
  • A second Google profile, /mcp/google/v2, brings the same rules to Gemini and Google Search. It has the same ten read-only tools and the six read scopes. Results and inputs carry no database IDs: get_customer takes a name, business name, email or phone; get_invoice and get_quote take a number. Several matches return needsChoice, and every tool declares an output schema. Failures the model can't fix (connection, permission, rate limit, outage) are JSON-RPC errors with Google's codes. Gemini moves to v2 once Google approves that version of the Servicebay connected app; until then it calls /mcp/google/v1, which is unchanged.
  • A customer named by an email address that the API's exact lookup refuses (one with an accented letter, say) is now matched against the customer list instead of failing.
  • search by an email or a phone number also returns the customers who have it in another letter case, written differently, or as a secondary phone, even when another customer has it exactly as typed. Before, an exact match hid them.
  • search and customer references now say how a phone number is matched, and the tool description states it: written any way (spaces, dashes, brackets, a + anywhere, leading zeros), and a number of at least 8 digits also finds the same number with up to 3 more digits in front, such as a country or an area code (3456 7890 finds 02 3456 7890). A number with a + inside brackets, such as (+61) 400 000 001, is now read as a phone number. When the customer list cannot be read, on any page, search says so in its note, or fails, instead of answering with fewer customers.
  • With more than 500 customers, a customer named by an email or phone that is not stored exactly as typed is answered too_many_to_match (use the customer's name or search) instead of "not found": they may be past the first 500. search by such an email or phone says so in its note. The search description now also says that two numbers find each other either way round, and that a number of 8 digits or more is a job number only when customers are not being searched.
  • A customer named by a phone number or email is no longer settled by the exact lookup alone: when the customer list cannot be read the answer is the error, and with more than 500 customers it is too_many_to_match, for a read as for a change. Before, a read took the one customer with that main phone and could miss another who has the same number as a secondary phone.
  • A customer reference of 6 or 7 digits alone (5550101) is read as a phone number and finds 555 0101; before, it was read as a name.

Security

  • A revoked, paused, expired or narrowed API key stops (or narrows) on its very next call at the MCP server too. It used to keep working there for up to a minute.
  • A connected app is credited, in the stock history and the job log, by what Servicebay verified about it: its hostname, or its own name marked (unverified). A hostname on shared hosting (*.pages.dev, *.github.io, …) is marked too. See Stock.
  • messageParams.source and messageParams.apiKeyName on a job message are written by the API and ignored when sent. Editing a message never changes who wrote it: a message written in the app is no longer marked source: "api" after an edit through the API.
  • An API key's name is cleaned of invisible formatting characters wherever it is shown, and a new name containing them is refused.
  • The consent screen and the developer portal no longer load a connected app's logo from its own server; they show its initials.
  • An expired API key can no longer be rotated, and a grace period never extends the old key past its own expiry.
  • Customer records: a value is returned only under a column the response lists and that is not secret.
  • If Servicebay cannot check whether an OAuth connection was revoked, the request is refused with 503 instead of being let through. Retry it.
  • The consent screen and the API key screen now say that writing jobs and invoices also takes and moves stock.
  • The site sends an enforced Content-Security-Policy that names every host a page may reach.
  • Dependencies updated (Next.js, the MCP SDK, Zod, Firebase Admin).

Good to know

  • Calendar events and scheduled jobs written through the API are copied to team members' Google and Outlook calendars, like ones made in the app.

October 2026

  • OAuth: POST /revoke (RFC 7009) and automatic clean-up of expired connections.
  • MCP: customer lookups by email or phone no longer fail on "no match".
  • Google Connected Apps profile at /mcp/google/v1.

September 2026

  • Scope version 2 (entity:read|write|delete, bundles, write no longer implies delete), scoped API keys, OAuth 2.1 with PKCE, and the MCP server.
  • Recurring schedules, forms (read-only), job line items, invoice reminders, share links, and the activity log.