Skip to content

API_DOCS.md

Latest commit

 

History

History
113 lines (88 loc) · 3.12 KB

API_DOCS.md

File metadata and controls

113 lines (88 loc) · 3.12 KB

📝 Documentação da API

A Vector API é uma API RESTful simples e poderosa, projetada para ser a interface de comunicação entre seus agentes de IA e o banco de dados vetorial.

1. Endpoints

Método Endpoint Descrição
GET /health Verifica a saúde da API e a conexão com o PostgreSQL.
POST /memory Ingestão: Salva um novo item de memória (texto) no banco de dados.
POST /memory/search Busca: Realiza uma busca semântica por similaridade.

2. POST /memory (Ingestão de Memória)

Este endpoint é usado para salvar novos conhecimentos no banco de dados. O texto é automaticamente transformado em um vetor (embedding) antes de ser armazenado.

Payload de Exemplo (JSON)

{
  "user_id": "leonardo_prod_01",
  "content": "O IP do servidor de banco de dados é 192.168.1.100.",
  "metadata": {
    "source": "chat_session_20260106",
    "tags": ["infraestrutura", "ip_address", "postgresql"]
  }
}

Exemplo de Chamada (cURL)

curl -X POST "https://manus.escossio.dev.br/memory" \
     -H "Content-Type: application/json" \
     -d '{
           "user_id": "leonardo_prod_01",
           "content": "O MAC Address da interface ether5 da RB3011 é 64:D1:54:53:7E:60.",
           "metadata": {
             "source": "mikrotik_config",
             "tags": ["rede", "rb3011", "mac_address"]
           }
         }'

3. POST /memory/search (Busca Semântica)

Este endpoint é usado para consultar a memória de longo prazo. A query_text é transformada em um vetor e comparada com todos os vetores armazenados.

Payload de Exemplo (JSON)

{
  "user_id": "leonardo_prod_01",
  "query_text": "Qual era mesmo o novo IP do meu DB?",
  "limit": 3
}
Campo Tipo Descrição
user_id string Identificador do usuário/agente para isolamento de dados.
query_text string A pergunta ou texto a ser buscado semanticamente.
limit integer O número máximo de resultados a serem retornados (default: 3).

Exemplo de Chamada (cURL)

curl -X POST "https://manus.escossio.dev.br/memory/search" \
     -H "Content-Type: application/json" \
     -d '{
           "user_id": "leonardo_prod_01",
           "query_text": "Onde eu anotei o endereço MAC da RB3011?",
           "limit": 1
         }'

Estrutura da Resposta (JSON)

A API retorna uma lista de resultados ordenados por similaridade (score).

[
  {
    "content": "O MAC Address da interface ether5 da RB3011 é 64:D1:54:53:7E:60.",
    "metadata": {
      "source": "mikrotik_config",
      "tags": ["rede", "rb3011", "mac_address"]
    },
    "score": 0.9876,
    "timestamp": "2026-01-06T17:00:00Z"
  }
]

4. GET /health (Verificação de Saúde)

Endpoint simples para verificar se a API está rodando e conectada ao banco de dados.

Exemplo de Chamada (cURL)

curl https://manus.escossio.dev.br/health

Resposta Esperada (JSON)

{
  "status": "ok",
  "message": "API de Memória para MANUS v0.1.0 está no ar!",
  "db_status": "connected"
}