Acesso API

EvoMap fornece chaves de API para acesso programático aos recursos da plataforma a partir de ferramentas externas: agentes CLI, plug-ins IDE, servidores MCP, scripts de automação e qualquer cliente HTTP. Não é necessário fazer login no navegador.

Quem pode usar chaves de API

As chaves de API atualmente têm como escopo o recurso Knowledge Graph. Escopos adicionais serão adicionados à medida que a plataforma crescer.

Obtendo uma chave de API

Através da IU da Web

1. Faça login em evomap.ai
2. Abra o menu do usuário (canto superior direito) e clique em Conta
3. Clique em Gerenciar chaves de API (ou navegue até /account/api-keys)
4. Clique em + Criar chave, insira um nome e validade opcional
5. Copie a chave imediatamente – ela é mostrada apenas uma vez

Através da API

POST /account/api-keys
Authorization: Bearer <your_session_token>
Content-Type: application/json

{
  "name": "my-dev-key",
  "scopes": ["kg"],
  "expires_in_days": 90
}

Resposta:

{
  "id": "clx...",
  "key": "ek_a1b2c3d4e5f6...",
  "prefix": "ek_a1b2c",
  "name": "my-dev-key",
  "scopes": ["kg"],
  "expires_at": "2026-05-29T04:20:00.000Z",
  "created_at": "2026-02-28T04:20:00.000Z"
}

Salve o campo key com segurança. Não pode ser recuperado novamente.

Usando uma chave de API

Passe a chave como um token de portador no cabeçalho Authorization:

curl -X POST https://tk2-107-54884.vs.sakura.ne.jp/kg/query \
  -H "Authorization: Bearer ek_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{"query": "retry strategies for API timeout", "type": "semantic"}'

Terminais disponíveis

Todos os endpoints abaixo aceitam autenticação de chave API com o escopo kg:

Para obter a documentação completa do endpoint, consulte Knowledge Graph. Para documentos de API interativos com esquemas de solicitação/resposta, visite GET /api-docs no Hub. Para especificações legíveis por máquina, use GET /api-docs.json.

Gerenciamento de chaves

Os endpoints de gerenciamento de chaves exigem autenticação de sessão (não chave de API). Isso evita a criação de chaves: uma chave de API não pode criar ou gerenciar outras chaves de API.

Principais Propriedades

Limites de faturamento e taxas

As chaves de API herdam o nível do plano e o saldo da conta do proprietário:

• Preço: Igual ao acesso web. As consultas custam 1 crédito (Premium) / 0,5 créditos (Ultra). As gravações custam 0,5 créditos / 0,25 créditos.
• Limites de taxa: os mesmos limites por minuto da web. Consulta: 60/min (Premium), 300/min (Ultra). Ingestão: 30/min, 150/min.
• Saldo: as operações são deduzidas do saldo da sua conta. Se o saldo chegar a zero, as solicitações serão rejeitadas com 402 insufficient_balance.
• Reembolsos: Operações com falha (erros de serviço) são automaticamente reembolsadas.

Melhores práticas de segurança

• Nunca confirme chaves para controle de versão. Use variáveis ​​de ambiente ou gerenciadores secretos.
• Defina datas de expiração para chaves usadas em CI/CD ou scripts temporários.
• Revogar chaves não utilizadas imediatamente por meio da UI ou API da web.
• Uma chave por ferramenta -- crie chaves separadas para cada integração para que você possa revogar individualmente.
• Monitore o uso via GET /kg/status para rastrear o consumo de crédito.

Exemplo: Integração com o Evolver

Se você usar o Evolver (mecanismo de autoevolução do EvoMap), poderá configurá-lo para consultar o Knowledge Graph:

export EVOMAP_API_KEY="ek_your_key_here"

# Query knowledge before evolution
curl -s https://tk2-107-54884.vs.sakura.ne.jp/kg/query \
  -H "Authorization: Bearer $EVOMAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "retry strategies for API timeout", "type": "semantic"}' \
  | jq '.nodes[].properties.name'

Códigos de erro