API de busca

Busca de texto completo

GET /api/search/

Busque nós por título e conteúdo usando a classificação por relevância BM25.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
q	string	sim	—	Consulta de busca
connection_id	UUID	não	primeira conexão do usuário	Conexão específica na qual realizar a busca
size	int	não	50	Número máximo de resultados
highlight	bool	não	true	Incluir trechos destacados
type	string	não	all	Filtro: page, database ou user

Exemplo:

curl -H "Authorization: Bearer <jwt_token>" \
  "https://ivgraph.com/api/search/?q=project+planning&size=10"

import requests

resp = requests.get(
    "https://ivgraph.com/api/search/",
    headers={"Authorization": "Bearer <jwt_token>"},
    params={"q": "project planning", "size": 10}
)
results = resp.json()["results"]

const resp = await fetch(
  "https://ivgraph.com/api/search/?q=project+planning&size=10",
  { headers: { Authorization: "Bearer <jwt_token>" } }
);
const { results } = await resp.json();

Resposta:

{
  "query": "project planning",
  "total": 8,
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "type": "page",
      "title": "Project Planning Guide",
      "score": 12.5,
      "highlight": "...comprehensive <em>project</em> <em>planning</em> methodology..."
    }
  ]
}

Preenchimento automático

GET /api/search/suggest/

Preenchimento automático baseado em prefixos para buscar enquanto você digita.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
q	string	sim	—	Prefixo (mínimo de 2 caracteres)
size	int	não	10	Número máximo de sugestões

Exemplo:

curl -H "Authorization: Bearer <jwt_token>" \
  "https://ivgraph.com/api/search/suggest/?q=pro"

Resposta:

{
  "prefix": "pro",
  "suggestions": [
    {"id": "uuid-1", "title": "Project Alpha", "type": "page"},
    {"id": "uuid-2", "title": "Product Roadmap", "type": "page"},
    {"id": "uuid-3", "title": "Projects Tracker", "type": "database"}
  ]
}

Busca semântica

GET /api/search/semantic/

Busca por similaridade vetorial usando representações vetoriais. Encontra conteúdo conceitualmente semelhante, não apenas correspondências de palavras-chave.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
q	string	sim	—	Consulta em linguagem natural
connection_id	UUID	não	primeira conexão do usuário	Conexão na qual realizar a busca
size	int	não	10	Número máximo de resultados

Exemplo:

curl -H "Authorization: Bearer <jwt_token>" \
  "https://ivgraph.com/api/search/semantic/?q=how+do+we+handle+user+onboarding"

Resposta:

{
  "query": "how do we handle user onboarding",
  "total": 5,
  "search_type": "semantic",
  "results": [
    {"id": "uuid-1", "type": "page", "title": "New User Welcome Flow", "score": 0.89},
    {"id": "uuid-2", "type": "page", "title": "Onboarding Checklist", "score": 0.82}
  ]
}

Busca híbrida

GET /api/search/hybrid/

Combina a busca por palavras-chave com BM25 e a busca semântica vetorial para obter resultados que aproveitam o melhor das duas abordagens.

Parâmetros: os mesmos da busca semântica.

Exemplo:

curl -H "Authorization: Bearer <jwt_token>" \
  "https://ivgraph.com/api/search/hybrid/?q=authentication+flow"

Nós semelhantes

GET /api/search/similar/{node_id}/

Encontre nós semelhantes a um determinado nó com base em representações vetoriais.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
node_id	UUID	sim	—	ID do nó de origem (no caminho da URL)
connection_id	UUID	não	primeira conexão do usuário	Conexão na qual realizar a busca
size	int	não	10	Número máximo de resultados

Exemplo:

curl -H "Authorization: Bearer <jwt_token>" \
  "https://ivgraph.com/api/search/similar/550e8400-e29b-41d4-a716-446655440001/"

Conteúdo da página

GET /api/search/content/{page_id}/

Obtenha o conteúdo da página em Markdown e texto simples.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
page_id	UUID	sim	ID da página (no caminho da URL)

Exemplo:

curl -H "Authorization: Bearer <jwt_token>" \
  "https://ivgraph.com/api/search/content/550e8400-e29b-41d4-a716-446655440001/"

Resposta:

{
  "page_id": "550e8400-e29b-41d4-a716-446655440001",
  "title": "Project Alpha",
  "markdown": "# Project Alpha\n\nMain project page...",
  "plain_text": "Project Alpha\nMain project page...",
  "has_content": true
}

Gerenciamento de índices

POST /api/search/index/

Inicie a reindexação do índice do Elasticsearch para a conexão do usuário.

curl -X POST -H "Authorization: Bearer <jwt_token>" \
  "https://ivgraph.com/api/search/index/"

Resposta:

{"message": "Indexing complete", "index_name": "ivg_conn-uuid", "indexed_count": 342}

DELETE /api/search/index/

Exclua o índice de busca da conexão do usuário.

curl -X DELETE -H "Authorization: Bearer <jwt_token>" \
  "https://ivgraph.com/api/search/index/"

GET /api/search/connections/

Liste todos os índices de busca do usuário.

curl -H "Authorization: Bearer <jwt_token>" \
  "https://ivgraph.com/api/search/connections/"

Resposta:

{
  "user": "username",
  "connections": [
    {
      "connection_id": "conn-uuid",
      "schema_name": "airbyte_conn_uuid",
      "index_name": "ivg_conn-uuid",
      "document_count": 342,
      "last_sync": "2026-04-10T10:00:00Z"
    }
  ]
}

Erros

Status	Significado
400	Parâmetros de consulta ausentes ou inválidos
401	Não autenticado
404	Conexão não encontrada ou página não encontrada
503	Elasticsearch indisponível