GET /accounts/{accountId}/search

Busca full-text ranqueada na conta inteira, usando a coluna gerada search_tsv (migration 009) e o índice GIN.

searchMessages — GET /accounts/{accountId}/search?q=&limit=&offset=.

websearch_to_tsquery e não to_tsquery: o segundo é um parser estrito que LEVANTA ERRO em entrada que não seja uma expressão válida — um usuário digitando contrato & derrubaria a rota em 500. O primeiro aceita qualquer texto, entende a sintaxe que as pessoas já conhecem de buscador ("aspas" para frase, OR, - para excluir) e nunca falha por sintaxe. Numa caixa de entrada, busca que dá erro é pior que busca que não acha nada.

ts_rank_cd (e não ts_rank): leva em conta a proximidade entre os termos, o que importa quando alguém busca duas palavras que espera ver juntas.

Isolamento: o account_id do WHERE vem do path, mas só depois de ownsAccount provar que a conta é do caller — o mesmo gate das outras rotas de mensagem. O predicado no SQL é defense-in-depth: se o gate sumir num refactor, a query ainda não atravessa caixas.

Entradas: accountId no path; q obrigatório; limit (1..200, default 50) e offset (>= 0) opcionais.

Retorno: 200 {items, query, limit, offset}; 400 accountId ou q inválido; 403 conta de outro usuário; 500 erro de banco.

curl -sS -X GET 'https://mail-api.axuz.net/accounts/ACCOUNT_ID/search' \
  -H "Authorization: Bearer $AXUZ_TOKEN"

const res = await fetch("https://mail-api.axuz.net/accounts/ACCOUNT_ID/search", {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.AXUZ_TOKEN}`,
  },
});
if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
console.log(await res.json());

import os
import requests

res = requests.request(
    "GET",
    "https://mail-api.axuz.net/accounts/ACCOUNT_ID/search",
    headers={
        "Authorization": f"Bearer {os.environ['AXUZ_TOKEN']}",
    },
    timeout=30,
)
res.raise_for_status()
print(res.json())