API — Busca

O endpoint de busca executa busca híbrida (full-text + semântica) sobre issues de um workspace.

---

POST /api/v1/workspaces/:slug/search

Executa busca híbrida nas issues do workspace.

Body

{
  "query": "problema de autenticação no mobile",
  "project_ids": ["01J8X...", "01J8X..."],
  "limit": 10
}

Campo	Tipo	Obrigatório	Padrão	Descrição
query	string	Sim	—	Texto de busca
project_ids	array	Não	todos	Filtrar por projetos específicos
limit	integer	Não	10	Máximo de resultados (máx: 50)

Response 200

{
  "results": [
    {
      "id": "01J8X...",
      "key": "FE-7",
      "title": "Corrigir bug no login com Google — OAuth callback falhando",
      "description_excerpt": "...usuários com iOS 17 reportam falha no callback OAuth após atualização...",
      "type": "bug",
      "priority": "high",
      "status": {
        "name": "Em progresso",
        "category": "in_progress",
        "color": "#f59e0b"
      },
      "project": {
        "id": "01J8X...",
        "name": "Frontend",
        "identifier": "FE"
      },
      "assignee": {
        "name": "Gabriel Mowses",
        "avatar_url": null
      },
      "score": 0.94,
      "match_type": "hybrid"
    }
  ],
  "total": 3,
  "query": "problema de autenticação no mobile",
  "semantic_available": true
}

Campos do resultado

Campo	Descrição
score	Score de relevância 0.0–1.0 após reranking
match_type	fulltext, semantic ou hybrid
description_excerpt	Trecho relevante da descrição
semantic_available	Se a busca semântica está disponível (plano/config)

Exemplo

curl -X POST https://tasks.cloudface.tech/api/v1/workspaces/produto/search \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "problema de autenticação no mobile",
    "limit": 5
  }'

Como a busca funciona

1. Full-text search

Executa to_tsquery no PostgreSQL com os tokens da query. Suporta stemming em português e inglês. Usa os índices GIN sobre to_tsvector(title || ' ' || description).

2. Busca semântica

Se disponível (plano Profissional+ e Ollama configurado):

1. Gera o embedding da query via modelo bge-m3 (mesma dimensão dos vetores armazenados)
2. Executa ORDER BY embedding <=> query_vector LIMIT k no pgvector

3. Fusão por RRF

Os dois rankings são fundidos com Reciprocal Rank Fusion:

score_rrf(d) = Σ 1 / (k + rank_i(d))

onde k = 60 (padrão) e rank_i é a posição no ranking de cada fonte.

4. Reranker

Os top-20 resultados do RRF passam por um modelo cross-encoder que avalia (query, título+descrição) e produz um score final de 0–1. O resultado final é ordenado por esse score.

Busca sem semântica

Se semantic_available: false, a busca usa apenas full-text. A resposta tem o mesmo formato — match_type será sempre fulltext.