Développeurs · Clés API
Référence des clés API TypeHop
Une clé API permet à une app d’IA ou à votre propre code de lire les dictées synchronisées avec votre compte TypeHop, depuis n’importe quel appareil. Les clés sont en lecture seule : elles peuvent rechercher et lire les dictées et vos mots personnalisés, sans jamais rien modifier ni supprimer. L’accès passe par un seul point de terminaison MCP distant, si bien que des apps comme Claude Code, Cursor et Codex fonctionnent avec une seule ligne de configuration.
Créer une clé
- Ouvrez l’app TypeHop pour Mac et allez dans Intégrations → Clés API.
- Appuyez sur Créer une clé API et donnez-lui le nom de l’app ou de la machine qui l’utilisera, par exemple « Cursor sur mon portable ».
- Copiez la clé tout de suite. TypeHop ne stocke qu’un hash : la clé complète n’est donc affichée qu’une fois. Perdue ? Créez-en une nouvelle et révoquez l’ancienne.
Les clés commencent par thp_mcp_. La liste dans l’app indique les premiers caractères de chaque clé, sa date de création et sa dernière utilisation. Révoquer une clé bloque immédiatement toutes les apps qui l’utilisent.
Authentification
Envoyez la clé comme jeton Bearer à chaque requête. Il n’y a ni flux OAuth ni session à ouvrir.
- Point de terminaison
https://api.typehop.com/v1/mcp- Méthode
POSTuniquement.GETetDELETErenvoient 405.- En-tête
Authorization: Bearer thp_mcp_YOUR_KEY- Corps
- JSON-RPC 2.0,
Content-Type: application/json
Une clé manquante ou révoquée
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." } }Connecter une app d’IA
La plupart des gens n’appellent jamais le point de terminaison à la main. L’app Mac affiche la configuration exacte pour Claude Code, Cursor, VS Code, Windsurf, Codex, Gemini CLI, Zed et Claude Desktop sous Connecter une app, avec votre nouvelle clé déjà renseignée. Les mêmes extraits sont disponibles sur la page MCP. Par exemple, pour Claude Code :
claude mcp add --transport http typehop https://api.typehop.com/v1/mcp --header "Authorization: Bearer thp_mcp_YOUR_KEY"
Tout autre client compatible avec les serveurs MCP distants via Streamable HTTP fonctionne avec l’URL du point de terminaison et l’en-tête ci-dessus. Les connecteurs personnalisés de Claude.ai et ChatGPT nécessitent OAuth, que TypeHop ne prend pas encore en charge.
L’appeler depuis du code
Le point de terminaison parle le Model Context Protocol : des messages JSON-RPC 2.0 dans un POST, avec une seule réponse JSON en retour. Il est sans état : pas d’en-têtes de session ni d’événements envoyés par le serveur. Versions du protocole prises en charge : 2025-06-18, 2025-03-26, 2024-11-05.
1. Initialiser (facultatif, mais les clients MCP le font)
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. Lister les outils
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. Appeler un outil
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}}}'Réponse · 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
}
}Chaque dictée dans un résultat commence par une ligne d’en-tête : [created at · app · id <id>], puis le texte nettoyé. Transmettez cet id à get_dictation pour obtenir la transcription brute. Vous pouvez aussi envoyer un tableau d’au plus 20 messages en une seule requête ; les notifications (messages sans id) reçoivent 202 sans corps. ping est pris en charge.
Outils
Chaque outil est en lecture seule et renvoie du texte brut dans result.content[0].text.
search_dictations · Rechercher des dictées
Recherche en texte intégral dans tout ce que l’utilisateur a dicté. Renvoie d’abord les correspondances les plus récentes.
query(string, obligatoire): Mots ou phrase à trouver.limit(integer 1–50, par défaut 20)
recent_dictations · Dictées récentes
Les dernières dictées de l’utilisateur, éventuellement limitées aux derniers jours.
limit(integer 1–50, par défaut 20)days(integer 1–365): Uniquement les dictées des N derniers jours.
get_dictation · Obtenir une dictée
Une dictée par id : le texte nettoyé et la transcription brute.
id(string, obligatoire): L’id affiché dans les résultats de recherche ou récents.
list_dictionary · Mots personnalisés
Les mots et orthographes personnalisés de l’utilisateur (noms, jargon).
Aucun argument.
Quand un outil ne peut pas répondre (requête vide, id inconnu, échec de lecture temporaire), la réponse reste un résultat 200, avec isError: true et une phrase que le modèle peut lire.
Erreurs
Les erreurs de protocole sont renvoyées sous la forme d’un objet JSON-RPC error : { "code": <number>, "message": "<text>" }.
401 · -32001L’en-tête Authorization est manquant, ou la clé est invalide ou révoquée.400 · -32700Le corps n’est pas du JSON valide.413 · -32600Le corps dépasse 256 Ko.200 · -32600Le message n’est pas du JSON-RPC 2.0 ("jsonrpc": "2.0" ou "method" manquant).200 · -32601Méthode inconnue.200 · -32602tools/call a désigné un outil qui n’existe pas.500 · -32603Erreur serveur. Réessayez avec un délai croissant.
Limites et sécurité
- Clés actives
- Jusqu’à 10 par compte. Révoquez-en une pour en créer une autre.
- Taille de la requête
- 256 Ko par requête, jusqu’à 20 messages par lot.
- Résultats
- Jusqu’à 50 dictées par appel ;
recent_dictationsremonte au maximum 365 jours. - Portée
- Les dictées synchronisées avec votre compte, ainsi que vos mots personnalisés. Rien n’est écrit.
- Utilisez une clé par app ou par machine, pour pouvoir en révoquer une sans casser les autres.
- Gardez les clés sur votre ordinateur ou votre backend. Ne les mettez jamais dans du code de navigateur, un bundle d’app mobile ou un dépôt public.
- Si une clé fuite : révoquez-la dans Intégrations → Clés API. Elle cessera de fonctionner dès la requête suivante.
Des questions : support@typehop.com. Vous cherchez plutôt une vue d’ensemble ? Consultez l’API TypeHop.