Search

The app’s search box, GET /search and the MCP search tool use the same search service. Results are limited to the caller’s permissions.

Asking

GET /search?q=kingston&limit=5
Authorization: Bearer btl_…

Parameter	What it is
q	What to look for. Two characters at least, a hundred at most.
kinds	Optional. Only these, comma separated, from the list below.
limit	Optional. The most results of each kind, 1 to 20. 5 if left out.

The answer is a single list, best first across every kind:

{
  "items": [
    {
      "kind": "customer",
      "id": "0192…",
      "title": "Kingston Fish Bar",
      "detail": "KT1 1QN",
      "status": null,
      "date": null,
      "archived": false,
      "path": "/customers/0192…",
      "score": 0.9
    }
  ]
}

path is the page in the app that shows the record. score runs from 0 to 1 and compares across kinds, so the best customer and the best invoice can be put in order against each other.

Kinds and scopes

The route requires tenant:read plus the relevant scope for each result type. Types the caller cannot access are omitted rather than causing an error.

Kind	Matched on	Needs
customer	Trading and legal name, email, phone	customers:read
address	Name, street, town, postcode with and without the space	customers:read
order	Tracking reference, the shop’s reference, a one-off’s name and address	orders:read
invoice	Number as printed, number alone, who it is billed to	invoices:read
product	Name, short code, SKU	products:read
person	Name, email	members:read
vehicle	Name, registration with and without the space	rounds:write
base	Name, street, town, postcode	rounds:write

Vehicles and bases need rounds:write because rounds:read alone is a driver reading their own round, and the fleet is the office’s.

How it matches

What was typed is split into words on spaces and hyphens. Every word must appear somewhere in the record’s text, in any order and any case. Splitting on hyphens is what lets 7K3M-9QWX find a reference stored as 7K3M9QWX, and INV-BTL00042 find invoice 42.

A word of four letters or more also matches when it is close to a word in the record (trigram word similarity), which forgives a slip of the finger. Shorter words must match as typed.

A phone number is reduced to the same digits Bottle keeps a customer’s phone as, so +44 20 8546 1234 and 020 8546 1234 find the same customer. A number on its own is also tried as an invoice number.

All result types use this ranking: exact name match, name prefix, word prefix, substring, then fuzzy match. Archived records receive a 25% score reduction.