Unified search endpoint — find any record from your AI

GET /v1/search?q=... is the one-call lookup endpoint. Pass a free-text query and it substring-matches across every entity the API key has read scope for, returning grouped results.

Why it exists:
AI assistants need to find records by name. "The deal at Memorial Hospital." "Acme Corp." "fall festival." Without a unified search, the AI has to fan out across six list endpoints and filter client-side. /v1/search collapses that into one call.

Request:
GET /v1/search?q=acme&limit=10&entities=accounts,contacts
Authorization: Bearer turtini_...

Parameters:
• q (required) — free-text query, min 2 chars. Multi-word queries match when every token appears in some searchable field.
• limit — max matches per entity (1-50, default 10)
• entities — optional comma-separated whitelist (accounts, contacts, opportunities, articles, events, products, quotes, grants)

Response shape:
{
"query": "acme",
"totalMatches": 5,
"scoped": ["accounts", "contacts", "opportunities"],
"results": {
"accounts": [{ "id": "...", "name": "Acme Corp", ... }],
"contacts": [{ "id": "...", "firstName": "...", ... }],
"opportunities": [{ "id": "...", "name": "Acme renewal", ... }]
}
}

Searchable fields per entity:
• accounts: name, website, email, phone, industry
• contacts: firstName, lastName, email, phone, title
• opportunities: name, stage, description
• articles: title, summary, tags
• events: title, location, description, slug
• products: name, sku, family, description
• quotes: number, status, accountName
• grants: title, summary, category, funderName, tags

Required scope: at least one read scope. The endpoint silently skips any entity the key doesn't have access to and lists what it actually searched in the scoped[] array.

Implementation note (current):
V1 uses an in-memory substring filter on the most recent 500 docs per entity, with a 30-second cache. Queries hit Firestore at most once per entity per 30 seconds. For orgs with >5,000 docs per entity, an indexed prefix search will replace the in-memory filter — the endpoint shape stays the same.