TypeHop
Download

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

  1. Abra o app TypeHop para Mac e vá em Integrations → API keys.
  2. 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”.
  3. 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. GET e DELETE retornam 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 · -32001 O cabeçalho Authorization está ausente, ou a chave é inválida ou foi revogada.
  • 400 · -32700 O corpo não é um JSON válido.
  • 413 · -32600 O corpo é maior que 256 KB.
  • 200 · -32600 A mensagem não é JSON-RPC 2.0 (falta "jsonrpc": "2.0" ou "method").
  • 200 · -32601 Método desconhecido.
  • 200 · -32602 tools/call citou uma ferramenta que não existe.
  • 500 · -32603 Erro 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_dictations olha 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.

Other products from us:SmashSend·TidySupport·SuperBuilder·Inbounter·Blossu·KnowledgeSDK