Desenvolvedores · Chaves de API
Referência das chaves de API do TypeHop
Uma chave de API permite que um app de IA ou o seu próprio código leia os ditados sincronizados com a sua conta TypeHop, de qualquer dispositivo. As chaves são somente leitura: podem pesquisar e ler ditados e suas palavras personalizadas, nunca alterar ou excluir nada. O acesso passa por um único endpoint MCP remoto, então apps como Claude Code, Cursor e Codex funcionam com uma única linha de configuração.
Criar uma chave
- Abra o app TypeHop para Mac e vá em Integrations → API keys.
- Clique em Create API key e dê um nome com base no app ou na máquina que vai usá-la, por exemplo “Cursor no meu notebook”.
- Copie a chave imediatamente. O TypeHop guarda apenas um hash, então a chave completa é exibida uma única vez. Perdeu? Crie uma nova e revogue a antiga.
As chaves começam com thp_mcp_. A lista no app mostra os primeiros caracteres de cada chave, quando ela foi criada e quando foi usada pela última vez. Revogar uma chave interrompe imediatamente todos os apps que a usam.
Autenticação
Envie a chave como token Bearer em todas as requisições. Não há fluxo OAuth nem sessão para abrir.
- Endpoint
https://api.typehop.com/v1/mcp- Método
- Somente
POST.GETeDELETEretornam 405. - Cabeçalho
Authorization: Bearer thp_mcp_YOUR_KEY- Corpo
- JSON-RPC 2.0,
Content-Type: application/json
Chave ausente ou revogada
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="typehop-mcp"
{ "jsonrpc": "2.0", "id": null, "error": { "code": -32001, "message": "This token is invalid or was revoked." } }Conectar um app de IA
A maioria das pessoas nunca chama o endpoint manualmente. O app para Mac mostra a configuração exata para Claude Code, Cursor, VS Code, Windsurf, Codex, Gemini CLI, Zed e Claude Desktop em Connect an app, com a sua nova chave já preenchida. Os mesmos trechos estão na página de MCP. Por exemplo, no Claude Code:
claude mcp add --transport http typehop https://api.typehop.com/v1/mcp --header "Authorization: Bearer thp_mcp_YOUR_KEY"
Qualquer outro cliente que ofereça suporte a servidores MCP remotos via Streamable HTTP funciona com a URL do endpoint e o cabeçalho acima. Os conectores personalizados do Claude.ai e do ChatGPT exigem OAuth, que o TypeHop ainda não suporta.
Chamando pelo código
O endpoint fala o Model Context Protocol: mensagens JSON-RPC 2.0 em um POST, com uma resposta JSON de volta. Ele é stateless, então não há cabeçalhos de sessão nem server-sent events. Versões do protocolo suportadas: 2025-06-18, 2025-03-26, 2024-11-05.
1. Inicializar (opcional, mas os clientes MCP fazem isso)
curl https://api.typehop.com/v1/mcp \
-H "Authorization: Bearer thp_mcp_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-app","version":"1.0.0"}}}'2. Listar as ferramentas
curl https://api.typehop.com/v1/mcp \
-H "Authorization: Bearer thp_mcp_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'3. Chamar uma ferramenta
curl https://api.typehop.com/v1/mcp \
-H "Authorization: Bearer thp_mcp_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_dictations","arguments":{"query":"launch plan","limit":5}}}'Resposta · 200
{
"jsonrpc": "2.0",
"id": 3,
"result": {
"content": [
{
"type": "text",
"text": "[2026-11-03T09:14:22.000Z · Slack · id 3f6c1a2e-8b1d-4c55-9a0e-6b2f7d1e4c90]\nThe launch plan moves to next Tuesday..."
}
],
"isError": false
}
}Cada ditado em um resultado começa com uma linha de cabeçalho: [created at · app · id <id>], seguida do texto revisado. Passe esse id para get_dictation para obter a transcrição bruta. Você também pode enviar um array com até 20 mensagens em uma única requisição; notificações (mensagens sem id) recebem 202 sem corpo. ping é suportado.
Ferramentas
Todas as ferramentas são somente leitura e retornam texto simples em result.content[0].text.
search_dictations · Pesquisar ditados
Busca em texto completo em tudo o que o usuário ditou. Retorna primeiro as correspondências mais recentes.
query(string, obrigatório): Palavras ou frase a encontrar.limit(integer 1–50, padrão 20)
recent_dictations · Ditados recentes
Os últimos ditados do usuário, opcionalmente apenas dos últimos dias.
limit(integer 1–50, padrão 20)days(integer 1–365): Apenas ditados dos últimos N dias.
get_dictation · Obter um ditado
Um ditado por id: o texto revisado e a transcrição bruta.
id(string, obrigatório): O id exibido nos resultados de busca ou de recentes.
list_dictionary · Palavras personalizadas
As palavras e grafias personalizadas do usuário (nomes, jargões).
Sem argumentos.
Quando uma ferramenta não consegue responder (consulta vazia, id desconhecido, falha temporária de leitura), a resposta continua sendo um resultado 200, com isError: true e uma frase que o modelo consegue ler.
Erros
Erros de protocolo voltam como um objeto error do JSON-RPC: { "code": <number>, "message": "<text>" }.
401 · -32001O cabeçalho Authorization está ausente, ou a chave é inválida ou foi revogada.400 · -32700O corpo não é um JSON válido.413 · -32600O corpo é maior que 256 KB.200 · -32600A mensagem não é JSON-RPC 2.0 (falta "jsonrpc": "2.0" ou "method").200 · -32601Método desconhecido.200 · -32602tools/call citou uma ferramenta que não existe.500 · -32603Erro do servidor. Tente novamente com backoff.
Limites e segurança
- Chaves ativas
- Até 10 por conta. Revogue uma para criar outra.
- Tamanho da requisição
- 256 KB por requisição, até 20 mensagens por lote.
- Resultados
- Até 50 ditados por chamada;
recent_dictationsolha para trás no máximo 365 dias. - Escopo
- Os ditados sincronizados com a sua conta, mais as suas palavras personalizadas. Nada é gravado.
- Use uma chave por app ou máquina, para poder revogar uma sem quebrar as outras.
- Mantenha as chaves no seu computador ou backend. Nunca coloque uma em código de navegador, no pacote de um app mobile ou em um repositório público.
- Se uma chave vazar: revogue-a em Integrations → API keys. Ela deixa de funcionar na próxima requisição.
Dúvidas: support@typehop.com. Procurando uma visão geral? Veja a API do TypeHop.